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Rancher 实战 红 宇 书 


Rancher 是 非常 优秀 的 容器 管理 平台 ， 本 书 旨 在 沉淀 和 积累 相关 实战 文档 。 本 书 通 过 GitHub 
和 GitBook 平台 共同 承载 ， 并 实现 参与 者 的 协作 。 本 书 使 用 开源 社区 的 方式 ， 由 Rancher 用 
户 社区 合作 维护 。 


参考 源 : http://docs.rancher.com 
本 书 在 线 访问 网 址 : http://rancher.hidocker.io 


本 书 的 初始 化 版 本 ， 保 持 了 和 Rancher 文档 官网 同步 的 目录 结构 (为 了 维护 方便 ， 
RancherOS 被 当做 一 个 独立 章节 纳入 了 本 书 ) ; 为 了 方便 您 的 翻译 ， 请 建议 直接 下 载 
https://github.com/rancher/rancher.github.io 英文 源 站 到 本 地 【作为 英文 原文 的 离线 参考 ) ; 
然后 再 Fork https://github.com/martinliu/rancher-docs 到 自己 的 仓库 ， 并 从 自己 的 仓库 下 载 本 
书 电子 书 源码 到 本 地 ， 您 会 看 到 本 书 的 很 多 章节 还 都 是 空白 文章 ; 然后 您 就 可 以 可 以 开始 工 
作 了 。 本 书 的 第 一 个 阶段 性 目标 是 : 对 官方 英文 文档 做 1 : 1 的 翻译 。 然 后 是 收集 各 位 高 手 的 
原创 好 文 。 目 标 是 打造 出 一 份 很 实用 和 全 面 的 参考 资料 库 。 


如 果 你 没有 GitHub 的 使 用 经 验 ， 请 查看 这 个 视频 ， 否 则 忽略 此 段 ， 继 续 仔细 阅读 本 网 页 ; 视 
频 会 教会 您 纯 网 页 版 的 操作 和 协作 流程 ， 其 中 示例 了 如 何 把 6.1 访问 控制 做 英文 原文 的 初始 
化 ， 和 翻译 提交 。 视 频 点 这 里 。http://v.youku.com/v_show/id _XMTU1NDk4Mzc2OA 


Github 是 一 个 协作 平台 ，pull request 是 解决 冲突 的 方式 ， 你 提交 的 pull request 上 来 以 后 ， 
如 果 有 冲突 ， 在 这 种 情况 下 电子 书 源码 的 管理 员 需 要 解决 这 个 冲突 ， 从 两 个 冲突 的 pull 
request 中 选择 出 一 个 更 好 的 。 为 了 快速 响应 所 有 文档 参与 者 的 贡献 ， 现 在 征召 电子 书 源码 仓 
库 管 理 员 合 作者 (Collaborators) ; 如 果 您 提交 的 PR 被 三 次 接受 ， 且 您 有 意 参 与 源码 管理 工 
作 ; 您 就 可 以 申请 成 为 Collaborators ; 请 发 一 个 Issue 做 出 申请 ， 没 有 人 反对 的 话 ，2 天 内 
就 会 成 为 Collaborators 。 

为 了 避免 两 个 人 或 者 更 多 的 人 同时 开始 翻译 同一 篇 文章 ， 当 您 开始 决定 做 某 个 文章 的 时 候 ， 
请 通过 首 个 PR 来 标记 一 下 您 的 目标 文章 。 具 体 的 操作 说 明 : 打开 您 的 目标 文章 (空白 文 

章 ， 只 有 一 行 标题 的 那 种 ) ， 在 首 行 写 一 句 话 “本 文档 首 稿 正在 编辑 中 ， 请 随后 帮忙 

review >” (226164518) ， 提 交 一 个 更 新 PR， 等 您 的 PR 被 确认 之 后 ， 您 即 可 进入 了 独占 的 
编辑 时 段 。 您 选择 多 篇 文章 的 话 ， 请 在 同一 个 PR 中 一 次 性 提交 初始 化 标记 。 


本 书 源码 开源 托管 在 Github， 欢 迎 参 与 维护 : https://github.com/martinliu/rancher-docs > # 
献 者 名 单 见 GitHub contributors 页 面 。 


欢迎 参与 线 上 讨论 。 





e QQ #1 
e 群 名 称 : Rancher 实 战 红 宝 书 群 1 
e #5 : 314700162 


为 了 您 能 顺利 领取 到 相关 纪念 品 〈 首 批 为 Rancherlogo 定制 版 Tshirt) ， 请 加 入 以 上 QQ 
群 ， 并 用 Github ID 备注 自己 的 姓名 。 详情 见 http://hidocker.io/book/ 


本 书 的 结构 
希望 能 形成 一 本 书 三 卷 的 结构 ， 系 统 而 完整 的 介绍 这 个 独特 的 容器 管理 平台 。 
第 一 部 分 


主要 介绍 Rancher 自身 的 原理 用 法 等 ， 希 望 用 户 可 以 快速 地 把 这 款 开 箱 即 用 的 容器 技术 使 用 
起 来 。 它 将 覆盖 Rancher 管理 平台 服务 器 测 的 所 有 必要 功能 。 


主要 介绍 RancherOS， 这 款 专门 为 容器 定制 的 精简 OS 的 相关 的 内 容 。 


第 三 部 分 


吸纳 现 有 的 各 种 实战 文章 ， 包 括 其 它 周边 的 配套 话题 。 如 容器 平台 的 监控 运 维 ; 基于 此 的 
DevOps 的 实践 ; 在 共有 与 中 的 最 佳 实践 ; 与 大 数据 或 者 私有 云 的 相关 话题 。 


参与 协作 


为 了 提高 参与 的 效率 ， 并 省 去 在 Gitbook 上 的 操作 的 步骤 。 请 直接 加 入 本 书 在 GitHub 上 的 源 


代码 协作 来 参与 到 文档 的 维护 中 来 。 


参与 步骤 : 注册 Github 账号 ， 克 隆 本 书 源 码 ， 下 载 到 本 机 ， 编 辑 目 标 文章 ， 推 送 到 自己 的 仓 


库 ， 提 交 pull request 到 本 书 源码 ，PR 通过 之 后 ， 您 的 贡献 自动 跟 新 到 线 上 版 本 。 


在 网 页 上 就 可 以 完成 所 有 文章 编辑 和 提交 工作 ， 操 作 流 程 在 这 里 


http://v.youku.com/v_show/id_XMTU1NDk4Mzc20A 网 页 版 直接 操作 ， 请 随时 保存 ， 以 免 网 


络 中 断 导致 的 信息 丢失 。 


具体 操作 步骤 (Github 命令 行 版 ) 


在 GitHub 上 fork 到 自己 的 仓库 ， 如 docker_userrancher-docs， 然 后 clone 到 本 地 ， 并 设置 


用 户 信息 。 


$ git clone git@github.com:martinliu/rancher-docs.git 
$ cd rancher-docs 

$ git config user.name "yourname" 

$ git config user.email "your email" 


修改 代码 后 提交 ， 并 推送 到 自己 的 仓库 。 


$ #do some change on the content 编辑 您 参与 的 文章 
$ git commit -am "Fix issue +1: change helo to hello" 
$ git push 


在 GitHub 网 站 上 提交 pull request ° 


定期 使 用 项 目 仓 库 内 容 更 新 自己 仓库 内 容 。 


$ git remote add upstream https://github.com/martinliu/rancher-docs 
$ git fetch upstream 

$ git checkout master 

$ git rebase upstream/master 

$ git push -f origin master 


或 者 使 用 GitHub Desktop 图 形 化 客户 端 完成 以 上 所 有 操作 ， 推 荐 使 用 Atom 作为 本 地 
件 编辑 器 。 


添砖加瓦 


.mk X 


本 书 不 仅 限 于 对 Rancher 官方 原文 的 翻译 ， 更 关注 任何 相关 实战 文档 的 汇聚 。 如 果 您 有 这 个 
想法 ， 请 在 https://github.com/martinliu/rancher-docs/issues 页 面 点 击 New Issue 按钮 ， 在 
Issue 中 描述 您 想 提交 的 “文章 标题 "和 位 置 。|ssue 被 处 理 之 后 源码 管理 员 会 尽快 初始 化 这 篇 
文章 ， 您 同步 更 新 到 本 地 ， 就 可 以 开始 编辑 上 传 这 篇 文章 了 。 


主要 版 本 历史 


e v0.5.0 完成 了 第 一 版 全 目录 ， 章 节 条 目 为 126 行 ， 更 新 了 Readme 
e。 v0.5.1 跟 新 了 协作 方法 ， 用 提交 初始 化 标记 PR 替换 了 之 前 的 认领 方式 ， 上 传 了 网 页 版 
github 操作 视频 。 


Rancher 概述 


Rancher 是 以 在 生产 环境 中 运行 容器 为 目标 而 构建 的 开源 软件 平台 。 随 着 Docker 容器 这 种 类 
型 的 应 用 工作 负载 的 逐渐 流行 ， 它 催生 了 很 多 与 之 相应 的 基础 架构 服务 ， 如 网 络 服务 、 存 储 
服务 、 负 载 均衡 ， 安 全 ， 服 务 发 现 和 资源 管理 。 


计算 资源 


Rancher 使 用 的 是 来 自 于 公有 云 或 私有 云 上 Linux 主机 的 裸 计 算 源 。 每 一 个 Linux 主机 既 
可 以 是 虚拟 机 ， 也 可 以 是 物理 机 。Rancher 对 每 一 个 主机 的 期 望 不 会 多 于 CPU? NA BE 
存储 和 网 络 连 接 。 从 Rancher 的 角度 看 来 ， 一 个 来 自 云 服务 商 的 a 的 物 
理 机 是 没 多 大 差异 。 


关键 功能 
Rancher 产品 的 关键 功能 包括 
1， 扩 主机 网 络 : Rancher 为 每 个 环境 生成 一 个 软件 定义 网 络 ， 为 扩 主 机 和 云 的 容器 之 间 提 
供 了 安全 的 网 络 通讯 。 
2. 容器 的 负载 均衡 。Rancher 提供 的 内 置 、 弹 性 负载 均衡 能 在 容器 之 间或 者 服务 之 间 分 发 
流量 。 负 载 均衡 服务 可 以 跨 多 个 云 工 作 。 


3. 持久 化 存储 服务 : Rancher 对 Docker 提供 持久 化 存储 服务 的 编排 ， 让 开发 者 在 部 署 容 
器 化 应 用 的 同时 可 靠 地 部 署 与 之 相应 的 存储 。 这 项 新 功能 基于 Docker 1.9 的 卷 插件 功 
能 ， 这 让 开发 人 员 可 以 更 加 方便 地 运行 需要 有 状态 数据 库 和 持久 存储 的 应 用 。 


4 服务 发 现 : Rancher 实现 了 分 布 式 服务 发 现 功能 ， 具 有 内 置 的 健康 检查 功能 ， 并 使 容器 
自动 地 注册 自己 到 相应 至 相应 服务 ， 并 且 各 种 服务 之 间 可 以 在 网 络 上 动态 地 彼此 发 现 。 


5.， 服务 升级 : u. ts ，Rancher 使 用 户 能 更 加 容易 地 升级 以 
a 。 这 让 新 版 本 的 服务 在 处 理 生 产 流 量 前 ， 有 机 会 在 其 所 依赖 的 生产 环 
境 中 被 校 验 和 pee o 


6， 资 源 管 理 : Rancher 支持 Docker Machine， 这 个 强大 的 工具 可 以 直接 地 对 各 种 云 提 供 商 
做 主机 部 署 。 然 后 Rancher 在 对 其 做 资源 监控 和 容器 部 署 管理 。 


7， 多 租户 和 用 户 环境 : Rancher 为 多 用 户 而 设计 ， 企 业 各 个 部 门 间 可 以 跨 应 用 生命 周期 协 
作 。 通 过 与 已 有 目录 服务 的 集成 ，Rancher 的 用 户 可 以 创建 独立 的 开发 ， 测 试 和 生产 环 
境 ， 然 后 邀请 相关 人 员 一 起 协作 地 管理 资源 和 应 用 。 


8 多 编排 引擎 支持 : Rancher 用 户 在 创建 环境 的 时 候 ， 可 以 为 他 们 的 容器 选择 不 同 的 容器 
编排 引擎 ， 默 认 是 Cattle， 或 者 是 Kubernets 和 Docker Swarm。 这 让 用 户 可 以 选择 任意 
市 场 领 先 的 调度 框架 的 同时 ， 依 然 能 利用 到 Ranher 的 其 它 所 有 功能 ， 如 : 应 用 商店 / 目 
录 ， 企 业 级 用 户 管理 ， 容 器 网 络 ， 和 存储 技术 。 


主要 使 用 接口 
用 户 有 三 种 方式 和 Rancher 交互 : 


1. 用 户 可 以 使 用 原生 Docker CLI 命令 行 或 者 API 接口 操作 Rancher ° Rancher 并 不 是 其 
它 那 种 把 原生 Docker 体验 给 遮盖 掉 的 编排 系统 或 者 管理 系统 。 随 着 Docker 平台 不 断 地 
发 展 ， 封 装 层 很 可 能 会 给 原生 的 Docker 功能 给 替代 。 而 Rancher 是 在 后 人 台中 工作 ， 这 
样 用 户 可 以 继续 使 用 原生 的 Dcoker CLI 和 Docker Compose 模板 。Rancher 通过 原生 
Docker CLI 来 用 Docker 标签 的 方式 传递 更 多 的 信息 ， 标 签 功能 是 Rancher Labs 贡 献 到 
Docker 1.6 中 的 功能 。 因 为 Rancher 支持 原生 的 Docker CLI 和 API， 像 Kubernets 这 样 
第 三 方 的 工具 可 以 在 Rancher 自如 的 使 用 。 

2. 用 户 可 以 通过 叫做 rancher-compose 的 命令 行 工 具 和 rancher 交互 。 rancher-compose 
工具 可 以 让 用 户 基 于 Docker Compose 模板 在 Rancher 服务 器 上 启动 一 套 多 容器 和 服务 
的 应 用 。 rancher-compose 工具 支持 标 准 的 docker-compose.yml 文件 格式 o 一 个 可 选 的 

rancher-compose.yml 文件 可 以 用 KAT docker -compose.yml 定义 扩展 或 者 覆盖 原 有 的 
定义 。 

3. 用 户 还 可 以 使 用 Rancher 的 图 形 界 面 来 操作 。Rancher 图 形 界 面 可 以 完成 很 多 配置 工 
作 ， 如 配置 访问 控制 权限 ， 管 理 环境 ， 添 加 Docker 镜像 库 等 。 另 外 它 为 管理 容器 基础 架 
构 和 服务 提供 了 简单 易 用 的 用 户 体验 。 


Rancher 的 主要 功能 如 下 的 示意 图 ， 它 可 以 被 运行 在 任何 云 上 ， 并 且 有 三 种 方式 与 之 交互 。 
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本 文档 的 线索 


把 Rancher 运行 起 来 是 比较 容易 的 。 如 果 您 有 一 个 Linux 虚拟 机 在 笔记 本 上 或 者 云 主 机 ， 阅 
读 快速 安装 指南 迅速 获得 第 一 手 实 战 经 验 。 


如 果 您 想 安装 一 套 生产 级 别 的 Rancher 环境 ， 请 按照 Rancher 安装 这 一 章 的 指导 ， 来 部 署 
配置 Rancher 服务 器 并 添加 节点 进来 。 


在 您 开始 使 用 Rancher 之 前 ， 请 一 定 阅 读 基本 概念 这 一 节 ， 以 了 解 Rancher 是 如 何 工作 
的 。 


系统 配置 这 一 章 描述 了 大 量 Rancher 服务 器 部 署 和 运行 之 后 ， 如 何 做 各 种 必要 的 一 次 性 配置 
工作 。 


这 三 章 -- 使 用 Docker 原生 命令 行 ,使 用 Rancher Compose, 和 Rancher 图 形 界 面 -- 描述 了 使 
用 Rancher 功能 的 三 种 主要 方式 。 


升级 Rancher 是 很 重要 的 一 章 ， 如 果 您 在 生产 环境 中 运行 Rancher 。 
为 Rancher 做 贡献 这 包含 了 如 何 参 与 Rancher 开源 社区 的 信息 。 


Rancher OS 完整 的 这 种 定制 版 容器 操作 系统 的 安装 、 配 置 和 使 用 ， 在 英文 原始 文档 中 和 本 文 
为 平行 的 一 份 文档 。 为 了 翻译 协作 和 使 用 的 方便 性 ， 目 前 把 它 收录 为 本 书 的 一 个 章节 。 


快速 安装 指南 
本 文档 首 稿 正在 编辑 中 ， 请 随后 帮忙 review。 


在 本 文中 ， 我 们 将 做 一 个 Rancher 系统 的 快速 安装 ， 即 在 一 台 Linux 机 器 上 安装 并 运行 所 有 
几乎 所 有 的 必要 功能 。 


准备 Linux 主机 


先 安 装 一 个 64 位 的 Ubuntu 14.04 Linux 主机 ， 其 内 核 必须 高 于 3.10 。 或 者 其 它 同等 的 Linux 
发 行 版 。 你 可 以 使 用 一 台 笔 记 本 、 一 个 虚拟 机 或 者 一 台 物 理 的 服务 器 。 请 确保 目标 安装 Linux 
主机 的 内 存 至 少 1GB 。 


然后 安装 Docker 在 这 个 Linux 主机 上 > TRAZ Docker 网 站 的 安装 说 明 。 


启动 Rancher 服务 器 


启动 Rancher 服务 器 所 需要 做 的 动作 就 只 有 一 条 命令 。 在 启动 了 这 个 容器 之 后 ， 我 们 将 能 查 
看 到 这 个 运行 中 的 服务 器 的 日 志 。 


sudo docker run -d --restart=always -p 8080:8080 rancher/server 
显示 Rancher 服务 器 的 容器 ID， 赫 换 containerid 

sudo docker ps 

显示 并 查看 Rancher 服务 器 的 日 志 

sudo docker logs -f containerid 


ft wt e 


启动 Rancher 服务 器 可 能 需要 花 几 分 钟 时 间 。 这 取决 于 您 下 载 Rancher Server 镜 像 的 速度 。 
当日 志 中 显示 “.... Startup Succeeded, Listening on port...” 以 后 ，Rancher Ul 图 形 界面 现在 
就 能 正常 访问 了 。 


Rancher 服务 器 的 图 形 界 面 访问 端口 是 8080 ， 通 过 在 浏览 器 中 访问 这 个 网 址 
http://linux_host ip:8080 , 您 就 可 以 打开 Rancher 服务 器 的 图 形 界面 。 如 果 您 的 浏览 器 和 
Rancher 服务 器 都 运行 在 同一 台 服 务 器 上 ， 你 需要 使 用 主机 的 真实 Ip 地 址 ， 如 : 
http://192.168.1.100:8080 > MAX http://localhost:8080 或 者 http://127.0.0.1:8080 


注意 : Rancher 的 访问 控制 在 初始 安装 时 并 没有 配置 ， 你 的 Rancher 服务 器 图 形 界 面 和 


API 能 在 任何 能 访问 到 您 的 IP 地 址 的 地 方 被 访问 到 。 我 们 建议 配置 访问 控制 参考 访问 控 
制 . 


添加 主机 


为 简化 操作 ， 我 们 将 添加 运行 Rancher 服务 器 容器 的 主机 。 而 在 实际 的 生产 环境 中 ， 我 们 建 
议 使 用 专用 的 主机 来 运行 Rancher 服务 器 。 


通过 点 击 图 形 界 面 的 Infrastructure 标签 来 添加 主机 ， 然 后 您 将 会 看 到 Hosts 页 面 。 
Rancher 会 提示 您 选择 一 个 IP 地 址 。 这 个 IP MELA a eerie 添加 的 主机 访问 到 。 
把 Rancher 服务 器 的 端口 通过 防火 墙 的 NAT 或 者 负载 均衡 器 暴露 出 来 ， 或 者 暴露 到 Internet 
上 在 有 些 情 况 下 是 很 有 用 的 。 如 果 你 的 A 或 者 本 地 IP 地 址 ， 例 如 

192.168.*.* 3 Rancher 将 打印 一 个 提示 信息 ， 告 诉 您 是 否 确认 这 个 IP 地 址 可 NER 访问 
到 。 


现在 我 们 添加 Rancher 服务 器 主机 自身 ， 因 此 我 们 可 以 忽略 这 个 提示 信息 。 点 击 oe ; 您 
将 进入 默认 的 Custom 选项 页 面 ， 您 在 这 可 以 得 到 运行 rancheragent 容器 的 命令 。 这 里 还 
有 其 它 的 公有 云 的 选项 ， 使 用 这 个 选项 可 以 实现 通过 docker-machine 去 局 as 点 。 在 

Web 界面 上 ，Rancher 提供 的 用 于 添加 主机 的 命令 如 下 : 


$ sudo docker run -d --privileged -v /var/run/docker.sock:/var/run/docker.sock rancher 
/agent:v0.7.9 http://172.17.0.3:8080/v1/scripts/DB121CFBA836F9493653:1434085200000:2Z0 
wUMd6f1zz44efikGhBPiveo 


由 于 我 们 正在 添加 Rancher 服务 器 的 主机 ， 我 们 需要 添加 这 个 主机 所 使 用 的 共有 IP © 
Rancher agent 命令 中 如 果 没 有 这 个 参数 ， 这 个 主机 的 IP 很 可 能 会 是 个 错误 的 配置 。 您 可 以 
添加 这 文 个 IP 地 址 在 Step 4， 这 将 会 修改 命 a> 并 加 入 一 个 环 境 变 量 


$ sudo docker run -e CATTLE_AGENT_IP=172.17.0.3 -d --privileged -v /var/run/docker.soc 
k:/var/run/docker.sock rancher/agent:v0.7.9 http://172.17.0.3:8080/v1/scripts/DB121CFB 
A836F9493653: 1434085200000: 2ZOwUMd6fIzz44efikGhBP1veo 


13347 Rancher 服务 器 的 主机 上 运行 这 个 命令 。 


4484 Rancher 的 页 面 中 点 击 Close 按钮 后 ， 您 会 被 返回 到 Infrastructure -> Hosts 页 面 。 
在 一 两 分 钟 后 ， 这 个 主机 将 自动 出 现在 这 里 


使 用 图 形 界 面 创建 一 个 容器 


进入 Applications -> Stacks 页 面 ， 如果 这 里 还 没有 服务 ， 你 可 以 点 击 "Add Service" 按钮 。 
你 可 以 输入 一 个 类 似 frstcontainer” 的 名 字 。 您 现在 使 用 默认 配置 并 点 击 Create 。Rancher 
将 开始 在 这 个 主机 上 启动 两 个 容器 。 一 个 容器 是 您 所 创建 的 名 为 * first_container ; 另外 一 个 
容器 是 Network Agent*， 这 是 个 由 Rancher 创建 的 系统 容器 ， 它 用 来 处 理 扩 主 机 联网 和 健康 
检查 等 任务 


不 管 你 的 主机 是 什么 IP 地 址 ，first_container 和 Network Agent 将 会 的 到 10.42.*.* MR 
的 IP 地 址 。Rancher 已 经 创建 了 能 在 不 同 主 机 之 上 的 让 所 有 容器 可 以 相互 通信 的 覆盖 网 络 。 


如 果 你 点 击 first_container 的 下 拉 菜 单 ， 你 可 以 执行 各 种 动作 ， 例 如 : 停止 容器 ， 查 看 日 
志 ， 或 者 进入 容器 的 控制 台 


使 用 Docker 原生 命令 创建 一 个 容器 


Rancher 会 显示 所 有 在 主机 上 的 容器 ， 即 使 有 些 容器 是 在 图 形 界面 之 外 创建 的 。 在 主机 的 
shell 命令 行 里 创建 一 个 容器 。 


$ docker run -it --name=second_container ubuntu:14.04.2 


在 图 形 界 面 中 ， 你 将 看 到 second_container 在 你 的 主机 上 出 现 ! 如 果 你 通过 退出 命令 行 来 
退出 用 命令 方式 创建 的 容器 ， 在 Rancher 图 形 界 面 中 将 立刻 显示 这 个 容器 的 状态 为 停止 


Rancher 可 以 对 带 外 发 生 的 事件 作出 反应 ， me 显示 状况 如 实地 整合 在 它 的 视图 中 。 


前 的 
你 能 了 解 更 多 信息 在 使 用 Docker 原生 命令 行 这 一 章 。 
通过 命 


如 果 你 查看 容器 second_container 的 IP nn 你 会 注意 到 他 不 在 10.42.*.* MEP OC 


的 IP 地 址 是 通过 Docker 后 台 服 务 获 得 的 。 命令 行 方式 创建 容器 的 正常 的 结果 。 


如 果 我 希望 通过 命令 行 创 建 的 容器 依然 具有 Ranger EMMA HE? 我 们 所 需要 做 的 
就 仅仅 是 O o 


$ docker run -it --label io.rancher.container.network=true ubuntu:14.04.2 


标签 io.rancher.container.network 让 我 们 通过 命令 行 传递 了 一 个 通 这 样 Rancher 会 为 
把 容器 配置 为 连接 到 禾 盖 网 络 。 
创建 一 个 多 容器 应 用 


我 们 已 经 展示 了 如 何 创 建 当 个 容器 ， 并 把 他 们 连接 到 跨 主 机 的 网 络 。 然 而 大 多 数 丨 实 世 界 中 
的 应 用 都 是 由 多 种 服务 构成 的 。 例 vo WordPress 应 用 是 由 下 列 服务 组 成 的 : 


1， 一 个 负载 均衡 服务 。 负 载 均 衡器 把 Internet 流量 转发 给 WordPress 应 用 。 
2. 一 个 由 两 个 WordPress 容器 组 成 的 WordPress 服务 
3， 一 个 由 一 个 MySQL 容器 组 成 的 数据 库 服务 


负载 均衡 器 的 目标 地 是 WordPress 服务 ，WordPress 服务 连接 到 MySQL 服务 
在 这 一 章 里 ， 我 们 将 在 Rancher 中 逐步 地 创建 和 部 署 WordPress 应 用 堆栈 。 


在 Rancher 的 图 形 界 面 中 ， 点 击 Applications -> Stacks， 点 击 Add Service 按钮 来 添加 一 
个 服务 


首先 ， 我 们 将 使 用 mysql 镜像 来 创建 一 个 名 为 database 的 数据 库 服务 。 在 Command 标签 
里 ， 添 加 环境 变量 MYSQL_ROOT_PASSWORD=pass1 ， 点 击 Create 按钮 。 然 后 我 们 会 立刻 进入 堆 
栈 页 面 ， 这 里 包含 了 所 有 服务 。 


然后 ， 再 次 点 击 Add Service 按钮 来 添加 另外 一 个 服务 。 我 们 将 添加 一 个 WordPress 服务 并 
连接 到 mysql 服务 。 让 我 们 使 用 mywordpress 做 名 称 ， 使 用 wordpress 镜像 。 我 们 将 拉动 滚 
动 条 增加 此 服务 的 容器 数量 到 2。 在 Service Links 标签 中 ， 添 加 database 服务 ， 并 提供 
mysql 名 称 。 就 想 在 Docker 中 一 样 ， 当 你 选择 了 mysql 后 ，Rancher 将 从 所 连接 的 数据 库 服 
务 中 连接 必要 的 环境 变量 到 WordPress 镜像 中 。 然 后 点 击 Create > 


最 后 ， 我 们 来 创建 负载 均衡 器 。 点 击 Add Service 按 钮 傍 边 的 下 拉 菜 单 。 选 择 Add Load 
Balancer。 提 供 像 wordpressib 这 样 的 名 称 ， 并 选择 一 个 源 端口 和 你 将 用 来 访问 wordpress 
应 用 的 主机 上 的 目标 端口 。 在 这 个 例子 中 ， 我 们 把 这 两 个 端口 都 使 用 so 。 目 标 服务 将 是 
mywordpress 。 点 击 Save ° 

至 此 我 们 的 多 服务 应 用 堆栈 创建 完毕 ! Æ Applications -> Stack 页 面 ， 我 们 将 能 够 在 负载 均 
衡器 的 开放 端口 处 找到 一 个 连接 。 点 击 这 个 连接 ， 浏 览 器 将 新 打开 一 个 窗口 ， 它 将 显示 
wordpress 应 用 。 


使 用 Rancher Compose 创建 一 个 多 容器 应 用 


在 这 一 个 部 分 ， 我 们 将 使 用 名 为 rancher-compose 的 命令 行 工具 来 创建 上 一 节 里 已 经 创建 和 
部 署 的 相同 的 WordPress 应 用 。 


命令 行 工 具 rancher-compose 的 功能 和 流行 的 docker-compose 命令 行 工具 类 似 。 它 使 用 相同 
的 docker-compose.yml 文件 来 在 Rancher 上 部 署 应 用 。 你 能 在 rancher -compose.yml 文件 中 
制定 更 多 的 属性 ， CAD fe th docker-compose.yml 文件 。 


在 上 一 节 里 ， 我 们 创建 了 一 个 具有 一 个 负载 均衡 器 的 WordPress 应 用 。 如 果 你 已 经 在 
Ranher 中 创建 了 它 ， 你 能 直接 在 图 形 界面 的 堆栈 的 下 拉 菜 单 中 选择 Export Config 来 直接 下 
载 文件 。 docker -compose.yml 和 rancher -compose.yml 文件 内 容 将 与 下 面 实例 类 似 : 


docker-compose.yml 


mywordpress: 
tty: true 
image: wordpress 
links: 
database: mysql 
stdin_open: true 
wordpresslb: 
ports: 
=- 80:80 
tty: Erue 
image: rancher/load-balancer-service 
links: 
mywordpress: mywordpress 
stdin_open: true 
database: 
environment: 
MYSQL_ROOT_PASSWORD: passı 
EME enue 
image: mysql 
stdin_open: true 


rancher-compose.yml 


mywordpress: 
scale: 2 
wordpresslb: 
scale: 1 
load_balancer_config: 
haproxy_config: {} 
health_check: 
port: 42 
interval: 2000 
unhealthy_threshold: 3 
healthy_threshold: 2 
response_timeout: 2000 
database: 
scale: 1 


JA Ranher 图 形 界面 中 点 击 Download CLI KT rancher-compose 可 执行 文件 ， 这 个 链接 位 
于 页 面 的 页 脚 。 我 们 提供 了 Windows，Mac 和 Linux 的 不 同 的 版 本 。 


为 了 使 用 rancher-compose 在 Rancher 中 局 动 服务 ， 你 需要 设置 一 些 必 须 的 变量 。 你 需要 在 
Rancher 图 形 界 面 中 创建 一 个 environment API Key ° Ad API > 4 5% Add API Key ° 4% 
存 用 户 名 (access key) 和 密码 (secret key)。 设 置 rancher-compose 所 需要 的 环境 变 


B 


Y : RANCHER_URL , RANCHER_ACCESS_KEY ， 和 RANCHER_SECRET_KEY ° 


2 


# 设置 Rancher 的 环境 变量 


$ export RANCHER_URL=http://server_ip:8080/ 


# 设置 访问 密 钥 ， 类 似 : username 
$ export RANCHER_ACCESS_KEY=<username_of_key> 
# 设置 安全 密 钥 ， 类 似 : password 


$ export RANCHER_SECRET_KEY=<password_of_key> 


现在 进入 保存 docker -compose.yml 和 rancher -compose.yml 文件 的 目 k? 2 并 运行 下 面 的 命 


令 。 


$ rancher-compose -p Newwordpress up 


在 Rancher 中 ， 一 个 名 为 NewWordPress 的 新 堆栈 将 被 创建 ， 并 且 具 有 了 所 以 的 服务 。 


A 


Ak 


A 


Rancher 


单 节 点 服务 器 安装 


Rancher 使 用 基于 Docker 容器 的 部 署 方式 。 仅 需 简单 地 启动 两 个 容器 即 可 运行 。 一 个 容器 用 
于 管理 Rancher 服务 ， 其 他 容器 使 用 代理 的 方式 管理 主机 或 节点 。 


ay 
an 


e 任何 支持 Docker 1.10.3 的 Linux 发 行 版 。 其 中 RancherOS > Ubuntu > RHEL/CentOS 7 
经 过 了 更 多 的 测试 

e 1GB AË 

e MySQL 服务 ， 并 且 设 置 max_connections > 150 


~ _ eu 
启动 Rancher 服务 器 
在 安装 了 Docker 的 服务 器 上 可 以 很 简单 的 使 用 命令 启动 Rancher 服务 器 。 


$ sudo docker run -d --restart=always -p 8080:8080 rancher/server 


Rancher Ul 


Rancher 的 Ul 和 API 默认 工作 在 8080 3% 7 » Docker 镜像 下 载 后 ， 还 需要 1-2 分 钟 才 可 以 
成 功 局 动 并 显示 页 面 。 


访问 以 下 地 址 : http://<SERVER_IP>:8080 ， 这 里 <SERVER_IP> 是 指 运行 Rancher 服务 器 的 主 
机 用 于 网 络 访问 的 IP 地 址 。 


一 旦 UI 处 于 启动 和 运行 状态 ， 就 可 以 开始 添加 主机 。 主 机 添加 到 Rancher 服务 器 中 后 ， 您 
可 以 开始 添加 服务 或 使 用 Rancher catalog 启动 模板 。 
开启 活动 目录 或 OpenLDAP 支持 (TLS) 


为 了 开启 Rancher 活动 目录 或 OpenLDAP 支持 (TLS)，Rancher Server 容器 在 启动 时 需要 加 
载 证 书 。 您 需要 在 运行 Rancher Server 的 Linux 主机 上 保存 证 书 。 


启动 Rancher 服务 器 并 使 用 绑 定 挂 载 卷 的 方式 加 载 证 书 ， 证 书 在 容器 中 必须 使 用 ca.crt 命 
名 o 


$ sudo docker run -d --restart=always -p 8080:8080 \ 
-v /dir_that_contains_the_cert/cert.crt:/ca.crt rancher/server 


您 可 以 通过 检查 Rancher 服务 器 容器 日 志 确 认 ca.crt 是 否 已 经 成 功 的 传递 给 了 Rancher AR 


$ docker logs <server_container_id> 


在 日 志 的 开始 ， 会 提示 证 书 ca.crt 已 经 添加 。 


DEFAULT_CATTLE_RANCHER_COMPOSE_WINDOWS_URL=https://releases.rancher.com/compose/beta/l 
atest/rancher-compose-windows-386.zip 
Adding ca.crt to Certs. 


Updating certificates in /etc/ssl/certs... 1 added, © removed; done. 
Running hooks in /etc/ca-certificates/update.d.... 

done. 

done. 


[BOOTSTRAP] Starting Cattle 


REER MYSQL & 


如 果 你 想 将 容器 内 数据 库 持久 化 在 主机 上 ， 可 以 在 启动 Rancher 服务 容器 时 ， 绑 定 并 挂 载 
MySQL 数据 卷 。 


$ sudo docker run -d -v <host_vol>:/var/lib/mysql --restart=always -p 8080:8080 ranche 
r/server 


使 用 这 个 命令 ， 数 据 库 将 持久 化 保存 在 主机 上 。 如 果 您 已 有 一 个 Rancher 服务 器 容器 ， 请 参 
照 我 们 的 升级 文档 。 


使 用 外 部 数据 库 


如 果 您 更 希望 使 用 外 部 的 数据 库 运 行 Rancher 服务 器 ， 请 参照 如 下 操作 连接 Rancher 到 数据 
库 。 您 需要 一 个 已 经 创建 好 的 数据 库 ， 但 是 不 需要 创建 任何 数据 库 对 象 ，Rancher 将 会 自动 
创建 所 有 相关 的 数据 库 对 象 。 


Rancher 服务 器 需要 使 用 以 下 环境 变量 ， 并 通过 docker run 命令 启动 Rancher 服务 器 来 连 
接 外 部 数据 库 。 


e CATTLE_DB_CATTLE_MYSQL_HOST: 数据 库 实 例 的 主机 名 或 |P 地 址 
e CATTLE_DB_CATTLE_MYSQL_PORT: 3306 
e CATTLE_DB_CATTLE_MYSQL_NAME: 数据 库 名 


e CATTLE_DB_CATTLE_USERNAME: 用 户 名 
e CATTLE_DB_CATTLE_PASSWORD: 密码 


数据 库 名 和 用 户 名 必须 已 经 存在 ，Rancher 不 会 去 创建 数据 库 。 


这 是 一 个 用 于 创建 数据 库 和 用 户 的 SQL 命令 。 


sql CREATE DATABASE IF NOT EXISTS cattle COLLATE = 'utf8_general_ci' CHARACTER SET = ' 
utf8'; GRANT ALL ON cattle.* TO 'cattle'0'%' IDENTIFIED BY 'cattle'; GRANT ALL ON catt 
le.* TO 'cattle'@'localhost' IDENTIFIED BY 'cattle'; 


以 上 命令 创建 了 名 为 ‘cattle’ 的 数据 库 ， 创 建 了 用 户 名 为 “cattle' 的 用 户 。 


创建 了 数据 库 和 用 户 后 ， 使 用 环境 变量 参数 ， 并 启动 Rancher 服务 器 。 


$ sudo docker run -d --restart=always -p 8080:8080 \ 
-e CATTLE_DB_CATTLE_MYSQL_HOST=<hostname or IP of MySQL instance> \ 
-e CATTLE_DB_CATTLE_MYSQL_PORT=<port> \ 
-e CATTLE_DB_CATTLE_MYSQL_NAME=<Name of Database> \ 
-e CATTLE_DB_CATTLE_USERNAME=<Username> \ 
-e CATTLE_DB_CATTLE_PASSWORD=<Password> \ 
rancher/server 











使 用 HTTP 代理 环境 变量 


为 了 使 用 HTTP 代理 ， 需 要 修改 Docker 服务 支持 代理 。 在 Rancher 服务 器 启动 前 ， 编 
# /etc/defalut/docker 文件 指定 您 的 代理 并 重新 启动 Docker 服务 


$ sudo vi /etc/default/docker 


在 这 个 文件 中 编辑 #export http_ E //127.0.0.1:3128/" 指向 您 的 代理 。 保 存 修改 并 
重新 启动 Docker 服务 ， 每 个 操作 系统 重启 Docker 服务 的 方式 是 不 同 的 。 


> 


注意 


cal 


如 果 您 使 用 systemd 运行 Docker » 14% Fé Docker 文档 配置 HTTP 代理 。 


为 了 加 载 Rancher catalog ， 需 要 在 启动 Rancher 服务 器 时 加 载 HTTP 代理 的 环境 变量 信 
Bo 


IS 


$ sudo docker run -d \ 
-e http_proxy=<proxyURL> \ 
-e https_proxy=<proxyURL> \ 
-e no_proxy="localhost,127.0.0.1" \ 
--restart=always -p 8080:8080 rancher/server 


如 果 不 使 用 Rancher catalog ， 则 使 用 正常 方式 运行 启动 Rancher Server 命令 。 


在 Rancher 中 添加 主机 ， 无 需 使 用 HTTP 代理 。 


译 者 : XiaoBao Zhang 


From : http://docs.rancher.com/rancher/installing-rancher/installing-server/ 


多 节点 高 可 用 (HA) 


基于 Rancher v1.0.1 


基本 配置 需求 


e 多 节点 的 HA 配置 i end 


o 节点 需要 开放 的 端 


AER 


@ 全 局 访问 : TCP 340 22, 80, 443, 18080 (TR: 用 于 在 集群 启动 前 查看 并 


管理 栈 ) 
m 节点 间 连 接 : 


= UDP 端口 
= TCP 端口 : 


e MySQL 数据 库 
o 至 少 1GB 内 存 
o 每 Rancher 服务 器 节 
连接 ) 
。 外 部 负载 均衡 器 


建议 配置 


e 每 个 Rancher 服务 器 节 
的 物理 内 存 


: 500 , 4500 


2181 , 2376 , 2888 , 3888 , 6379 


点 50 个 连接 (如: 3 节点 的 高 可 用 部 署 至 少 需要 支持 150 个 


点 应 该 有 4GB 或 8GB 可 用 内 存 ， 意 味 着 至 少 需要 8GB 或 16GB 


e MySQL 数据 库 应 该 使 用 高 速 的 磁盘 
。 对 于 睦 正 的 高 可 用 ， 建 议 使 用 主 从 的 MySQL， 并 做 适当 的 备份 。 由 于 存在 事物 锁 ， 可 以 
选择 Galera 或 强制 写 入 单 节点 的 方式 。 


配置 高 可 用 的 准备 


1. 根据 使 用 外 部 数据 库 启 


动 单 节点 说 明 部 署 一 个 至 少 拥 有 1GB 内 存 的 MySQL 数据 库 ， 


但 是 不 要 使 用 其 中 启动 Rancher 服务 器 的 相关 指令 。 因 为 默认 情况 下 ， 用 户 只 能 从 本 地 
访问 数据 库 ， 你 需要 授权 所 有 Rancher 服务 器 节点 对 其 的 网 络 访问 。 
2. 配置 一 个 外 部 负载 均衡 器 并 将 端口 80 和 443 的 流量 指向 运行 Rancher Server 的 节点 


池 。 
3. en 本 文 准备 所 有 节点 


u en 需求 。 (可 


选 ) 您 可 以 提前 拉 取 rancher/server 镜像 到 这 些 节点 上 。 


目前 ， 我 们 的 高 可 用 集群 支持 3 种 配置 。1 节 点 : 没有 高 可 用 ; 3 节点 : 任何 一 台 主 机 
可 以 宕 机 ; 5 节点 :任何 两 台 主 机 可 以 宕 机 。 


这 些 节点 可 以 分 布 在 同一 个 地 区 ， 并 使 用 稳定 的 高 速 链 路 连接 的 多 个 数据 中 心 ， 不 
建议 分 布 在 距离 较 远 的 区 域 中 。 如 果 你 选择 分 布 节点 在 同一 个 区 域 ，Zookeeper 可 
以 用 来 保证 集群 的 高 可 用 。 如 果 你 的 节点 分 布 在 不 同 的 数据 中 心 ， 那 么 你 只 能 保留 
问题 最 少 的 那个 区 域 。 


4 在 其 中 一 个 节点 上 ， 启 动 一 个 Rancher 服务 器 用 于 生成 配置 脚本 。 下 面 这 个 脚本 用 于 生 
成 Rancher 服务 器 同时 连接 到 外 部 数据 库 并 初始 化 数据 。 它 将 被 引导 高 可 用 部 署 过 程 。 
最 终 ，Rancher 服务 器 容器 将 使 用 此 步骤 替换 为 支持 高 可 用 的 Rancher 服务 器 容器 。 


$ sudo docker run -d -p 8080:8080 \ 

-e CATTLE_DB_CATTLE_MYSQL_HOST=<hostname or IP of MySQL instance> \ 
-e CATTLE_DB_CATTLE_MYSQL_PORT=<port> \ 

-e CATTLE_DB_CATTLE_MYSQL_NAME=<Name of Database> \ 

-e CATTLE_DB_CATTLE_USERNAME=<Username> \ 

-e CATTLE_DB_CATTLE_PASSWORD=<Password> \ 

-v /var/run/docker.sock:/var/run/docker.sock \ 











rancher/server:v1.0.1 


my 
ah 


请 耐心 等 待 ， 这 个 初始 化 步骤 可 能 要 15 分 钟 才 能 完成 


5. (TE) 预先 下 载 rancher/server 镜像 到 Rancher 节 这 里 下 载 的 镜像 可 用 于 配置 
脚本 生成 Rancher 服务 器 。 


这 个 版 本 需要 是 第 四 步 中 所 使 用 的 版 本 
$ sudo docker pull rancher/server:v1.0.1 


生成 配置 脚本 


1. 访问 Rancher 服务 器 地 址 http://<server_IP>:8s080 生成 脚本 。 在 Admin -> HA 确认 
Rancher 服务 器 已 经 成 功 连接 到 外 部 数据 库 。 如 果 没 有 正确 配置 ， 请 重复 上 一 节 中 的 步 
HE 1 fo 4 © 

2. 选择 集群 大 小 ， 应 该 为 您 的 Rancher 服务 器 节点 数量 ， 参 照 上 一 节 中 步骤 3 。 

3. 在 Host Registration URL 中 填写 外 部 负载 均衡 器 的 IPv4 地 址 或 主机 名 。 

4. 选择 您 想 使 用 的 证 书 类 型 。Rancher 服务 器 可 以 为 您 生成 一 个 自 签 名 证 书 或 者 使 用 自己 
的 有 效 证 书 。 

5， 点 击 Generate Config Script ° 

6. 下载 脚本 并 保存 到 本 地 。 

7. 保存 脚本 后 ， 停 止 用 于 生成 脚本 的 Rancher 服务 器 容器 。 


E #Rancher 3 T M 


1. 为 了 使 所 有 节点 支持 高 可 用 ， 你 需要 


PR 在 所 有 节点 上 使 用 配置 脚本 启动 Rancher 服务 器 。 
脚本 将 启动 一 个 Rancher 服务 器 


需要 
容器 并 连接 到 之 前 创建 的 外 部 数据 库 。 
注意 : 


请 确保 您 已 经 停止 用 于 生成 脚本 rancher-ha.sh Rancher 服务 器 容器 后 再 运行 配 
置 脚本 。 和 否则 ， 在 你 尝试 在 同一 个 节点 运行 配置 脚本 时 ， 将 会 有 一 个 端口 冲突 导致 
高 可 用 节 P 点 无 法 局 动 。 


2， 如 果 你 之 前 生成 配置 脚本 时 提供 了 Host Registration URL ， 请 导航 到 外 部 负载 均衡 器 
4] IP 或 主机 名 。 请 注意 ，Rancher 服务 器 的 用 户 界 面 可 能 需要 几 分 钟 才 可 以 使 用 。 如 果 
你 的 用 户 界面 仍 不 可 用 ， 请 参照 查看 并 管理 栈 o 


3. 一 旦 用 户 界 面 可 用 ， 您 将 可 以 添加 主机 到 Rancher 高 可 用 集群 。 在 Admin -> HA 标签 可 
以 查看 高 可 用 节点 的 数量 。 添 加 主机 前 ， 您 需要 保存 证 书 
/var/lib/rancher/etc/ssl/ca.crt 并 赋予 400 权限 到 您 要 添加 的 主机 上 。 注 册 命令 可 以 

自动 创建 使 用 并 管理 证 书 。 

4. 在 您 向 环境 中 添加 主机 后 ， 高 可 用 设置 已 经 完成 ， 您 可 以 开始 通过 用 户 界 面 添加 服务 ， 
从 目录 启动 模板 或 使 用 rancher-compose 启动 服务 

注意 : 


如 果 您 正在 使 用 AWS ， 你 需要 为 添加 到 Rancher 的 主机 配置 IP 。 如 果 你 想 添 加 
自 定 义 主机 ， 你 需要 在 配置 页 面 中 填写 公 网 IP ， 启 动 Rancher agent 的 命令 会 相 
应 改变 。 已 经 通过 页 面 添加 的 主机 ， 必 须 ssh 登陆 到 机 器 重启 Rancher agent 使 IP 


译 者 : XiaoBao Zhang 


From : http://docs.rancher.com/rancher/installing-rancher/installing-server/multi-nodes/ 


NO 


SSL 基 本 配置 


为 了 可 以 正常 使 用 https 地 址 访问 Rancher RAS > HR BALA EH Hp HKD AB © A 
时 ， 我 们 提供 了 一 些 配 置 NGINX 或 Apache 代理 的 例子 ， 当 然 ， 您 也 可 以 使 用 其 他 工具 。 


de 十 
需求 
除了 典型 的 Rancher 服务 器 需求 您 还 需要 : 


e 有 效 的 SSL 证 书 : 如 果 您 的 证 书 不 包含 在 Ubuntu CA 中 ， 请 参照 自 签名 证 书 说 明 o 
e 配置 DNS 记录 。 


启动 Rancher 服务 器 


在 我 们 的 示例 配置 方案 中 ， 所 有 流量 将 通过 代理 被 发 送 到 Rancher 服务 器 的 Docker 容器 
中 。 也 有 替代 的 配置 方案 可 以 实现 ， 但 这 个 示例 相对 比较 简单 。 启 动 Rancher 服务 器 ， 这 里 
我 们 添加 了 选项 --name=rancher-server 用 来 连接 代理 容器 和 Rancher 服务 器 容器 


$ sudo docker run -d --restart=always --name=rancher-server rancher/server 


ER: 


IS 


在 我 们 的 示例 中 ， 我 们 假设 代理 运行 在 单独 的 容器 中 。 如 果 您 的 代理 计划 由 主机 提供 服 
务 ， 需 要 将 Rancher 容器 的 soso 端口 映射 至 本 地 主机 ， 可 以 向 docker run 命令 添加 
参数 -p 127.0.0.1:8080:8080 实现 。 


如 果 您 想 使 用 现 有 的 Rancher 实例 ， 您 可 以 基于 现 有 的 Rancher 实例 创建 一 个 新 的 Rancher 
实例 。 


e # Rancher 实例 的 MySQL 数据 库 运 行 在 容器 内 ， 在 启动 新 的 Rancher 实例 时 ， 请 参照 
升级 说 明 创建 数据 容器 并 且 在 启动 时 添加 --volumes-from=<data_container> ° 

e # Rancher 实例 使 用 了 绑 定 挂 载 数据 库 的 方式 ， 请 参照 绑 定 挂 载 实例 升级 说 明 。 

e # Rancher 实例 使 用 外 部 数据 库 ， 则 直接 停止 并 删除 现 有 的 Rancher 实例 容器 ， 并 参照 
外 部 数据 库 连接 说 明 启动 新 的 容器 。 


注意 : 
在 新 的 Rancher 容器 运行 后 ， 请 确认 已 经 删除 了 昌 的 Rancher ZARZ GM» 
在 您 的 主机 重启 后 ， 因 为 我 们 在 docker run * a --restart=always 参数 ， 会 


en 


NGINX 配置 示例 


这 里 的 配置 是 NGINX 运行 的 最 低 配 置 ， 您 应 该 定制 配置 来 满足 您 的 需求 。 


— AN 
节点 设置 


e rancher-server 您 的 Rancher ee 。 您 必须 在 局 动 Rancher 服务 器 容器 的 
时 候 加 入 --name=rancher-server 选项 。 并 且 在 启动 NGINX 容器 的 时 候 加 入 -- 
link=rancher-server 选项 才能 使 这 些 配 置 正常 工作 。 

© <server> 可 以 任意 命名 ， 但 是 必须 保证 http 和 https 配置 中 的 名 称 相 同 。 


upstream rancher { 
server rancher-server:8080; 


server { 
listen 443 ssl; 
server_name <server>; 
ssl_certificate <cert_file>; 
ssl_certificate_key <key_file>; 


location / { 

proxy_set_header Host $host; 

proxy_set_header X-Forwarded-Proto $scheme; 

proxy_set_header X-Forwarded-Port $server_port; 

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 

proxy_pass http://rancher; 

proxy_http_version 1.1; 

proxy_set_header Upgrade $http_upgrade; 

proxy_set_header Connection "upgrade"; 

# This allows the ability for the execute shell window to remain open for up t 
o 15 minutes. Without this parameter, the default is 1 minute and will automatically c 
lose. 

proxy_read_timeout 900s; 


server { 
listen 80; 
server_name <server>; 


return 301 https://$server_name$request_uri; 


APACHE 配置 示例 


这 是 一 个 Apache 的 配置 


+ 、 
节点 设置 
èe <server_name> 是 您 Rancher 服务 器 容器 的 名 字 2 所 以 在 局 动 Apache 容器 时 需要 加 入 
--link=<server_name> 才能 使 配置 正常 工作 。 
eo 在 代理 配置 中 ， 您 需要 替换 rancher 为 您 的 信息 。 


<VirtualHost *:80> 

ServerName <server_name> 

Redirect / https://<server_name>/ 
</VirtualHost> 


<VirtualHost *:443> 
ServerName <server_name> 


SSLEngine on 
SSLCertificateFile </path/to/ssl/cert_file> 
SSLCertificateKeyFile </path/to/ssl/key_file> 


ProxyRequests Off 
ProxyPreserveHost On 


RewriteEngine On 

RewriteCond %{HTTP:Connection} Upgrade [NC] 
RewriteCond %{HTTP:Upgrade} websocket [NC] 
RewriteRule /(.*) ws://rancher:8080/$1 [P,L] 


RequestHeader set X-Forwarded-Proto "https" 
RequestHeader set X-Forwarded-Port "443" 


<Location /> 
ProxyPass "http://rancher :8080/" 
ProxyPassReverse "http://rancher :8080/" 


</Location> 


</VirtualHost> 


更 新 主机 注册 


在 Rancher 配置 完成 后 ， 用 户 界 面 将 使 用 https://<your domain>/ 访问 。 在 添加 主机 之 
前 ， 您 需要 正确 配置 SSL 方式 的 主机 注册 地 址 。 


在 AWS ELB 后 使 用 SSL 运行 Rancher 


默认 情况 下 ，ELB 不 支持 在 HTTP/HTTPS 模式 下 局 用 websockets 。 由 于 Rancher 使 用 了 
websockets ， 则 ELB 必须 修改 配置 以 便 Rancher 的 websockets 可 以 正常 工作 。 


Rancher 的 ELB 配置 需求 


启用 代理 协议 模式 
e 配置 TLS/SSL 方式 的 前 端 以 及 TCP 方式 的 后 端 


使 用 自 签名 证 书 (测试 ) 
免责 声明 


这 个 配置 可 以 工作 在 单 节点 Rancher 服务 器 ( 非 HA 安 装 ) 模式 的 核心 服务 上 ， 没 有 人 验证 是 
否 支 持 Rancher 目录 是 否 被 支持 。 


Rancher Compose 命令 行 默认 需要 将 CA 证 书 存储 在 操作 系统 ， 请 参照 Golang 。 


及 务 器 ,从 备 条 件 


e CA 证 书 PEM 格式 的 文件 
o 已 经 签署 证 书 的 Rancher 服务 器 
e NGINX 和 Apache 配置 证 书 务 载 ， 并 反 向 代理 到 Rancher 服务 器 


pa 


Rancher 服务 器 


1. 使 用 修改 后 的 Docker 命令 启动 Rancher 服务 器 容器 。 证 书 必须 在 容器 中 被 命 


ca.crt 2 


$ sudo docker run -d --restart=always -p 8080:8080 -v /some/dir/cert.crt:/ca.crt 
rancher/server 


SL =» 
¡E I. 


如 果 你 正在 运行 NGINX 或 Apache a Be 访问 这 些 实例 ， 不 需要 通过 


Rancher 服务 器 的 8080 端口 访问 用 户 。 这 条 命令 将 会 配置 Rancher 服务 器 的 
证 书 链 ， 所 以 Rancher 的 服务 ， 如 机 ee ， 目录 和 compose #4) M4" Rancher 


服务 器 通讯 


2. 如果 您 正在 使 用 一 个 NGINX 或 Apache 容器 纯 载 证 书 ， 您 需要 在 启动 容器 的 命令 增加 
-link= 选项 。 


3. 通过 https 访问 Rancher 用 户 界 面 ， 即 https://rancher.server.domain ° 
4. 更 新 主机 注册 为 SSL 方式 。 


>. 
ER: 


除非 您 的 机 器 信任 了 用 于 签署 Rancher 服务 器 的 CA 人 证书 ， 否 则 当 你 访问 页 面 时 ， 


浏览 器 会 给 出 一 个 不 可 信 网 站 的 警告 信息 。 


添加 主机 
1. 如 果 您 想 添 加 主机 到 Rancher ， 您 必须 在 主机 上 以 pem 格式 将 CA 证 书 保存 到 


/var/lib/rancher/etc/ssl 目录 并 命名 为 ca.crt ° 
2. 添加 自 定义 主机 ， 也 就 是 从 用 户 界 面 粘贴 命令 。 命 令 已 经 加 入 了 -v 
/var/lib/rancher:/var/lib/rancher 选项 ， 所 以 文件 会 被 自动 复制 到 您 的 主机 上 。 


译 者 : XiaoBao Zhang 


From : http://docs.rancher.com/rancher/latest/en/installing-rancher/installing- 
server/basic-ssl-config/ 


无 互联 网 仿 问 


Rancher 服务 器 的 运行 可 以 不 需要 互联 网 ， 浏 览 器 需要 使 用 内 网 地 址 来 访问 Rancher 的 图 形 
界面 。Ranher 可 以 配置 私有 的 镜像 仓库 或 者 HTTP RE © 


在 没有 互联 网 访问 的 网 络 中 运行 Rancher 服务 器 有 下 面 几 个 功能 将 无 法 工作 正常 。 


e 从 网 页 界面 上 启动 容 ae 由 于 Rancher 是 通过 调用 docker-machine 来 在 公有 云 
里 创建 主机 ， 因 此 这 个 功能 会 不 能 用 。 您 依然 可 以 使 用 自 定义 主机 来 添加 主机 。 

e GitHub 用 户 认证 。 

e 来 自 Rancher Catalog 和 Community Catalog 的 模板 - 这 些 目 录 依 赖 从 Github 上 做 克 
隆 ， 但 是 您 将 仍然 可 以 使 用 添加 内 部 目录 来 把 私有 目录 添加 到 Rancher 中 。 


使 用 私有 镜像 仓库 


及 您 已 经 有 了 自己 的 内 部 私有 镜像 仓库 或 者 相关 方式 来 做 docker 镜像 的 分 发 。 如 果 您 
搭建 私有 镜像 仓库 方面 需要 帮助 ， 请 参考 Docker 官方 文档 Docker documentation for 
n: registries. 


Push 镜像 到 私有 仓库 


在 您 开始 安装 或 者 升级 Rancher 服务 器 之 前 ， 确 保 所 有 镜像 (例如 : rancher/server, 
rancher/agent, rancher/agent-instance) 都 已 经 分 发 到 所 有 服务 器 是 非常 重要 的 如 果 您 的 私 
有 镜像 仓库 中 没有 这 些 镜 像 ，Rancher 服务 器 将 可 能 变 得 不 稳定 。 


对 与 Rancher 服务 器 的 每 个 版 本 ， 它 所 需要 的 相应 的 Rancher agent 和 Rancher agent 
instance 镜像 的 版 本 将 会 在 Rancher 的 发 行 说 明文 档 中 。 


推送 镜像 到 私有 仓库 的 命令 


下 面 的 例子 适用 于 v1.0.1 版 本 的 Rancher 服务 器 去 访问 DockerHub 和 您 的 私有 仓库 。 我 们 
建议 在 私有 镜像 仓库 中 的 镜像 打上 相同 的 版 本 和 标签 。 


ancher/server 
$ docker pull rancher/server:v1.0.1 
$ docker tag rancher/server:v1.0.1 localhost :5000/<NAME_OF_LOCAL_RANCHER_SERVER_IMAGE> 
:v1.0.1 
$ docker push localhost:5000/<NAME_OF_LOCAL_RANCHER_SERVER_IMAGE>:v1.0.1 


rancher/agent 
$ docker pull rancher/agent:v1.0.1 
$ docker tag rancher/agent:v1.0.1 localhost:5000/<NAME_OF_LOCAL_RANCHER_AGENT_IMAGE>:v 
1.0.1 
$ docker push localhost:5000/<NAME_OF_LOCAL_RANCHER_AGENT_IMAGE>:v1.0.1 





$ docker pull rancher/agent-instance:v0.8.1 

$ docker tag rancher/agent-instance:v0.8.1 localhost :5000/<NAME_OF_LOCAL_RANCHER_AGENT 
_INSTANCE_IMAGE>: v0.8.1 

$ docker push localhost :5000/<NAME_OF_LOCAL_RANCHER_AGENT_INSTANCE_IMAGE>:v0.8.1 


3 > oe va 
从 私有 镜像 仓库 启动 Rancher 服务 器 
在 您 的 服务 器 上 ， 使 用 您 特定 的 Rancher 镜像 启动 Rancher 服务 器 。 我 们 使 用 特定 的 版 本 号 
标签 ， 而 不 是 latest 标签 ， 这 样 能 确保 您 工作 在 正确 的 版 本 组 合 上 。 
使 用 v1.0.1 版 本 示例 : 
$ sudo docker run -d --restart=always -p 8080:8080 \ 
-e CATTLE_BOOTSTRAP_REQUIRED_IMAGE=<Private_Registry_Domain>:5000/<NAME_OF_LOCAL_R 
ANCHER_AGENT_IMAGE>:v1.0.1 \ 
-e CATTLE_AGENT_INSTANCE_IMAGE=<Private_Registry_Domain>:5000/<NAME_OF_LOCAL_RANCH 


ER_AGENT_INSTANCE_IMAGE>:v0.8.1 \ 
<Private_Registry_Domain>:5000/<NAME_OF_LOCAL_RANCHER_SERVER_IMAGE>:v1.0.1 


Rancher 图 形 界 面 


图 形 界面 和 API 的 访问 是 通过 暴露 的 soso 端口 。 您 可 以 在 浏览 器 中 访问 这 个 URL: 


http://<SERVER_IP>:8080 


添加 主机 


mall 


在 进入 图 形 界 面 之 后 ， 点 击 Add Host #42 > 然后 Host Registration 页 面 会 立刻 显示 出 


Ko Az Save ° 


这 里 使 用 docker-machine 添加 公有 云 主 机 是 不 能 工作 的 。 点 击 Custom 图 标 来 获取 添加 主 
机 的 命令 。 


网 页 中 的 命令 将 被 配置 为 使 用 私有 镜像 仓库 去 拉 取 Rancher agent 镜像 。 


添加 自 定义 主机 命令 示例 


$ sudo docker run -d --privileged -v /var/run/docker.sock:/var/run/docker.sock <Privat 
e_Registry_Domain>:5000/<NAME_OF_LOCAL_RANCHER_AGENT_IMAGE>:v1.0.1 http://<SERVER_IP>: 
8080/v1/scripts/<security_credentials> 


使 用 HTTP 代理 


注意 ， 在 这 个 安装 中 浏览 器 是 通过 访问 私有 网 络 来 使 用 Rancher 的 图 形 界 面 。 


配置 Docker 使 用 HTTP 代理 


为 了 配置 HTTP 代理 ，Docker 后 台 进 程 在 被 修改 配置 之 后 可 以 使 Rancher 服务 器 和 
Rancher 主机 指向 HTTP 代理 。 在 启动 Rancher 服务 器 和 Rancher Agent 之 前 ， 编 辑 配置 文 
件 /etc/default/docker 添加 你 您 的 代理 服务 器 2 并 重启 Docker 服务 器 2 


$ sudo vi /etc/default/docker 


在 这 个 文件 中 ， 编 辑 #export http_proxy="http://127.0.0.1:3128/" 这 个 参数 去 指向 您 的 代理 
服务 器 。 保 持 变 更 并 重启 Docker 服务 。 重 启 Docker 容器 服务 器 在 不 同 Linux 发 行 版 上 可 能 
命令 不 同 。 


里 E 


注意 : 如 果 你 使 用 systemd 1847 Docker 服务 ， 请 参考 Docker 官方 的 关于 配置 HTTP A 
理 服务 器 的 文档 instructions 。 


启动 Ranher 服务 器 


当 使 用 代理 服务 器 的 时 候 ， We 服务 bone 动 时 不 需要 加 什么 特别 的 环境 变量 参数 的 。 
因此 ， 启 动 Rancher 服务 器 容器 的 命 是 常规 的 格式 。 


sudo docker run -d --restart=always -p 8080:8080 rancher/server 


Rancher 图 形 界 面 


图 形 界 面 和 API 的 访问 是 通过 暴露 的 soo 端口 。 您 可 以 在 浏览 器 中 访问 这 个 URL: 


http://<SERVER_IP>:8080 ° 


添加 主机 


在 进入 图 形 界 面 之 后 ， 点 击 Add Host 按钮 。 然 后 Host Registration 页 面 会 立刻 显示 出 
A> At Save > 


这 里 使 用 docker-machine 添加 公有 云 主 机 是 不 能 工作 的 。 点 击 Custom 图 标 来 获取 添加 主 
机 的 命令 。 


网 页 上 所 显示 的 命令 可 以 用 于 添加 任何 一 台 已 经 配置 好 Docker 使 用 HTTP 代理 的 主机 。 


添加 主机 


在 Rancher 中 ， 我 们 在 网 页 上 提供 了 关于 如 何 添加 公有 云 主 机 的 简洁 的 说 明 ， 还 包括 了 对 于 
不 支持 的 公有 云 如 何 做 的 说 明 。 在 Infrastructure 页 面 点 击 Hosts 菜单 ， 在 点 击 Add Host 
按钮 。 


主机 最 小 化 需求 


e 任何 能 支持 Docker 1.10.3 的 Linux 发 行 版 。 其 中 RancherOS, Ubuntu, RHEL/CentOS 7 
是 经 过 了 大 量 测试 的 。 

e 1GB AË 

e 建议 CPU A# AES-NI 特性 


工作 机 制 ? 


当 Rancher Agent 容器 在 主机 上 被 启动 了 之 后 ， 主 机 开始 去 连接 Rancher 服务 器 。 在 Add 
Host -> Custom 页 面 上 显示 的 很 长 的 添加 主机 命令 中 的 注册 秘 钥 被 Rancher Agent 用 来 做 对 
服务 器 端的 首次 连接 。 基 于 这 个 连接 ， 它 在 Rancher 服务 器 中 生成 了 一 个 Agent 账户 和 API 
密 钥 对 。 这 个 秘 钥 对 将 被 用 于 后 续 所 有 与 服务 器 端的 通讯 中 ， 这 种 认证 方式 和 环境 API ALAA 
的 认证 鉴 权 逻 辑 是 完全 一 致 的 。 


这 种 设计 是 假设 运行 在 外 部 的 主机 和 硬件 是 不 可 信 的 ， 由 于 这 些 资 源 具 有 潜在 的 风险 。Agent 
的 账号 仅仅 具有 它 所 需要 访问 的 资源 的 权限 ， 由 Agent 端 发 送 来 的 事件 实际 上 是 被 检查 的 。 
而 反方 向 并 没有 Agent 去 校 验 主机 的 机 制 ， 因 此 您 还 可 以 配置 用 于 Agent 和 Rancher 服务 器 
通讯 的 TLS 证 书 校 验 。 


不 同 环境 的 IPSec 密 钥 是 不 同 的 ， 它 被 保存 在 数据 库 里 ， 它 在 Agent 用 API 密 钥 对 注册 的 时 
候 被 发 送 给 主机 。 主 机 直接 的 连接 是 点 对 点 的 ， 是 AES 加 密 的 ， 这 种 加 密 是 可 以 被 大 多 数 型 
号 的 CPU 做 加 速 的 。 


添加 主机 


在 第 一 次 做 主机 添加 的 时 候 ， 你 需要 配置 一 次 Host Registration。 这 个 配置 决定 了 主机 用 什 
A DNS 名 称 或 者 IP 地 址 和 端口 来 连接 Rancher API。 黑 认 ， 我 们 已 经 选择 了 管理 I|P 和 端 

O goso 。 如 果 您 确定 需要 改变 IP 地 址 ， 请 确认 这 个 地 址 和 端口 是 被 用 来 连接 RAncher API 
的 。 在 任何 时 候 ， 您 能 更 新 Host Registration。 在 完成 主机 注册 的 配置 后 ， 点 击 Save 按钮 。 


我 们 支持 直接 添加 公有 云 主 机 或 者 云 里 已 经 创建 好 的 主机 。 对 于 公有 云 ， 我 们 通过 docker- 
machine 创建 主机 ， 并 支持 任何 支持 docker-machine 的 云 主机 镜像 。 


选择 你 想 添加 的 公有 云 主机 : 


e Adding Custom Hosts 

e Adding Amazon EC2 Hosts 

e Adding Azure Hosts 

e Adding DigitalOcean Hosts 

e Adding Exoscale Hosts 

e Adding Packet Hosts 

e Adding Rackspace Hosts 

e Adding Hosts from Other Drivers 


当 一 个 主机 被 添加 到 Rancher 中 ， 一 个 Rancher agent 容器 在 该 主机 上 被 启动 。Ranher 将 
自动 地 下 拉 正 确 版 本 号 的 rancher/agent 镜像 ， 来 运行 所 需 版 本 的 Agent。Agent 版 本 的 标 
签 必须 对 应 用 相应 的 Rancher 服务 器 版 本 。 


主机 标签 


对 于 每 一 个 主机 ， 你 可 以 通过 打 标 签 的 方式 来 组 织 它 们 。 当 启动 rancheragent 容器 的 时 候 ， 
标签 被 当做 环境 变量 来 添加 了 。 在 图 形 界 面 中 添加 主机 标签 是 用 键 / 值 对 格式 的 ， 其 中 见 必须 
是 唯一 标识 符 。 如 果 你 添加 了 两 个 相同 的 键 ， 并 使 用 不 了 不 同 的 值 ， 我 们 将 只 使 用 后 一 个 输 

入 的 键 / 值 对 。 


通过 给 主机 打 标签 ， 你 可 以 在 之 后 的 服务 调度 /负载 均衡 /服务 定义 ( schedule services/load 
balancers/services) 中 用 到 ， 如 给 某 个 服务 services 建立 一 个 它 运 行 主机 的 白 名 单 或 者 黑 名 
单 。 

如 果 您 打算 使 用 一 个 外 部 的 DNS 服务 external DNS service 那么 您 需要 让 DNS 记录 使 用 一 
个 IP 而 不 是 主机 IP to program the DNS records using an IP other than the host IP， 接 着 您 
需要 在 主机 上 使 用 这 文 个 标签 io.rancher.host. external_dns_ip= 
<IP_TO_BE_USED_FOR_EXTERNAL_DNS> 。 打 此 主机 标签 可 以 在 注册 这 个 主机 的 时 候 或 者 主机 已 经 
被 添加 到 Ranher 中 以 后 ， 它 应 该 在 外 部 DNS 服务 开始 使 用 到 之 前 做 。 这 个 标签 的 值 对 于 外 
部 的 DNS 服务 需要 是 符合 某 种 可 编程 的 逻辑 。 





当 使 用 图 形 界面 添加 不 同类 型 的 云 主机 的 时 候 ，rancheragent 命令 会 被 自动 地 启动 ， 并 会 使 
用 网 页 图 形 界面 中 您 所 制定 的 标签 。 


当 您 添加 自动 定义 主机 是 ， 您 可 以 在 图 形 界 面 中 添加 标签 ， 并 且 它 会 自动 地 添加 环境 变量 


( CATTLE_HOST_LABELS ) 标签 对 到 命令 中 。 


示例 


# 在 rancher/agent 命令 中 添加 一 个 主机 标签 
$ sudo docker run -e CATTLE_HOST_LABELS='foo=bar' -d --privileged \ 
-v /var/run/docker.sock:/var/run/docker.sock rancher/agent:v0.8.2 \ 
http: //<rancher -server -ip>:8080/v1/projects/la5/scripts/<registrationToken> 


t 添加 多 个 主机 标签 需要 使 用 `&` 来 连接 在 一 起 


$ sudo docker run -e CATTLE_HOST_LABELS='foo=bar&hello=world' -d --privileged \ 
-v /var/run/docker.sock:/var/run/docker.sock rancher/agent:v0.8.2 \ 
http://<rancher -server -ip>:8080/v1/projects/1a5/scripts/<registrationToken> 


注意 : rancher/agent 的 版 本 是 必须 和 Rancher 服务 器 版 本 保持 对 应 的 。 你 需要 在 这 里 
检查 自 定 义 命 令 中 所 使 用 的 版 本 号 标签 是 正确 的 。 


自动 化 添加 的 主机 标签 


Rancher 自动 化 生成 的 主机 标签 是 关于 主机 的 Linux 内 核 版 本 和 Docker 引擎 版 本 的 。 


键 值 y YE 
io.rancher.host.linux_kernel_version pe le il j Linux 
io.rancher.host.docker_version 主机 的 Docker 版 本 主机 所 安 安装 装 的 

(例如 : 1.10.3 ) Docker 引擎 版 本 。 


主机 在 代理 服务 器 后 面 

为 了 支持 主机 位 于 代理 服务 器 之 后 ， 您 将 修改 Docker 引擎 的 配置 来 指向 一 个 代理 服务 器 。 对 
此 的 描述 请 见 adding custom host page 页 面 。 

登录 云 主 机 


在 Rancher 启动 主机 之 后 ， 您 可 以 登录 这 些 主机 。 我 们 提供 在 创建 主机 过 程 中 生成 的 证 书 ， 
并 提供 下 载 。 点 击 主机 上 的 Machine Config 下 拉 菜 单 。 这 将 下 载 一 个 包含 所 有 证 书 的 tar.gz 
文件 。 


SSH 登录 到 您 的 主机 ， 打 开 命 令 行 工 具 ， 进 入 包含 所 有 证 书 文件 的 目录 ， 使 用 id rsa 证 
书 ， 用 如 下 命令 连接 。 


$ ssh -i id rsa root@<IP_OF_HOST> 


克隆 主机 


由 于 需要 使 用 一 个 访问 密 钥 来 启动 云 主 机 ， 您 可 能 想 通过 不 用 每 次 都 输入 密 钥 的 方式 来 更 简 
单 地 创建 另外 其 他 的 云 主 机 。Rancher 提供 了 a 建新 相似 的 云 主 机 。 从 主机 的 


下 拉 菜 单 中 选择 Clone 。 它 会 带 您 进入 Add Host 页 面 ， 这 个 页 面 上 的 密码 部 分 已 经 为 您 填写 
好 了 。 

`~ 2 ` 

编辑 主机 


这 个 菜单 位 于 一 个 已 经 添加 成 功 的 主机 的 下 拉 菜 单 中 。 在 Infrastructure -> Hosts 页 面 ， 该 
当 您 的 鼠标 滑 过 主机 的 下 拉 菜 单 按钮 的 时 候 出 现 。 如 果 您 点 击 主机 名 来 查看 主机 详情 ， 
菜单 在 页 面 的 右上 角 的 下 拉 菜 单 图 标 中 。 它 就 位 于 主机 状 旁 。 


如 果 您 点 击 Edit 菜单 ， 您 可 以 更 新 名 称 ， 描 述 或 者 主机 的 标签 。 
停 用 /激活 主机 


停 用 主机 将 把 主机 置 于 Inactive 状态 。 在 这 个 状态 里 ， 不 会 有 新 容器 被 部 署 。 该 主机 上 任何 
依然 照旧 运行 ， 对 容器 还 是 可 以 执行 动作 (启动 /停止 /重启 ) 。 这 个 
主机 将 会 继续 保持 和 Rancher 服务 器 的 连接 。 


当 一 个 主机 处 于 /nactive 状态 ， 您 还 可 以 通过 点 击 主机 的 下 拉 菜 单 中 的 Activate 使 其 返回 到 
Active 状态 。 


主意 : 如 果 一 个 主机 在 Rancher 中 已 经 宕 机 (例如 :处 于 reconnecting 或 inactive X 
) 


A) ， 您 将 需要 执行 一 次 健康 检查 来 让 您 的 服务 所 使 用 的 容器 在 另外 的 主机 上 启动 起 
来 。 

删除 主机 

为 了 从 服务 器 上 删除 一 个 主机 ， 您 将 需要 在 主机 的 下 拉 菜 单 中 做 这 些 操 作 。 


选择 Deactivate 。 当 主机 已 经 完全 处 于 停 用 状态 了 ， 主 机 将 进入 Inactive Ae o 选择 
Delete。 服 务 器 将 开始 执行 主机 删除 的 操作 。 在 完成 了 删除 动作 之 后 状态 先 会 

为 Removed。 在 彻底 重 图 形 界面 上 消失 之 前 它 还 会 进入 Purged 状态 。 

如 果 主 机 是 在 Ranher 中 创建 的 云 主 机 ， 主 机 会 将 被 从 云端 删除 。 如 果 云 主机 是 通过 使 用 自 定 
义 命令 添加 的 ， 主 机 将 依然 保留 在 云端 。 


注意 : 对 于 自 定义 主机 ， 所 有 容器 包括 Rancher agent 容器 都 还 会 保留 在 主机 上 。 


在 Rancher 之 外 删除 主机 


如 果 主 机 不 是 在 Rancher 中 删除 的 ，Rancher 服务 器 还 会 持续 连接 它 。 最 终 ， 这 个 主机 的 状 
态 会 持续 为 Reconnecting 状态 ， 即 使 它 没有 被 重 连 成 功 。 因 此 您 需要 在 图 形 界 面 中 通过 
Delete 删除 这 些 主机 ， 并 它们 清除 掉 。 


基本 概念 


在 本 章节 ， 我 们 将 介绍 Rancher 的 基本 概念 。 在 使 用 Rancher 之 前 ， 我 们 建议 你 对 这 些 概 念 应 
该 非常 熟悉 。 


“用 户 ? 定 义 了 什么 角色 在 一 个 环境 里 能 够 拥有 查看 或 管理 Rancher 资 源 的 权限 。Rancher 缺 省 
会 允许 单一 租户 的 访问 权限 ， 当 然 ， 管 理 员 可 以 定义 多 个 用 户 的 访问 权限 。 


在 你 开启 鉴 权 (authenticaiton) 之 前 ， 可 参照 访问 控制 . 


环境 


所 有 的 主机 和 任意 的 Rancher 资 源 ， 例 如 容器 、 负 载 均 衡器 等 ， 都 创建 并 归属 于 一 个 环境 。 
用 户 对 这 些 资源 查看 和 管理 的 权限 ， 由 环境 的 拥有 者 来 定义 。Rancher 目 前 支持 每 个 用 户 来 管 
理 和 邀请 其 它 用 户 进 入 他 的 环境 ， 并 且 能 够 为 多 种 工作 负载 来 定义 不 同 的 环境 。 例 如， 你 可 
以 创建 一 个 “Dev" 环 境 ， 另 外 再 创建 一 个 与 之 隔离 的 “生产 "环境 ， 每 个 环境 里 定义 不 同 的 资 

源 ， 从 而 限制 不 同 用 户 对 不 同 环境 的 访问 权限 。 


在 你 希望 和 其 它 用 户 共享 环境 之 前 ， 请 设置 访问 控制 。 


王 机 
在 rancher 环 境 里 ， 主 机 是 一 个 最 基本 的 资源 单元 ， 可 以 是 任意 的 虚拟 或 物理 的 Linux 服 务 器 ， 
对 这 些 服 务 器 的 要 求 如 下 : 


e 任意 的 Linux 发 行 版 ， 只 要 它 支持 Docker 1.10.3 ° 
e 能 够 和 Rancher 服 务 器 通过 预定 义 的 端口 号 ， 一 般 是 8080 ， 以 http 或 https 的 协议 进行 通 
TA ° 
e 和 同 环境 里 的 其 它 主 机 路 由 可 达 ， 从 而 能 够 利用 Rancher 的 跨 节 点 网 络 进 行 通讯 。 
Rancher 也 支持 Docker Machine 命 令 ， 从 而 允许 你 通过 任意 Rancher 支 持 的 接口 来 添加 主机 © 


在 Rancher 环 境 里 添加 主机 操作 之 前 ， 可 参考 添加 第 一 台 主 机 。 


网 络 


Rancher 通 过 使 用 IPsec 隧道 技术 ， 构 建 了 一 个 简单 和 安全 的 履 盖 (Overlay) 网 络 ， 来 支持 跨 
主机 节点 的 容器 通讯 。 如 果 和 希望 使 用 该 网 络 ， 容 器 在 通过 Rancher 启 动 时 ， 必 须 将 其 网 络 模式 
设 为 “Managed”， 或 着 在 Docker 命 令 行 启动 时 ， 提 供 额 外 的 标签 "--label 
io.ranchercontainernetwork=true"。 大 多 数 的 Rancher 网 络 功能 ， 例 如 负载 均衡 或 DNS 服 

务 ， 都 需要 容器 设 为 "Managed" 网 络 模式 。 


在 Rancher 网 络 里 ， 一 个 容器 将 被 分 配 一 个 Docker 的 桥接 IP 地 址 (172.17.0.0/16) 和 一 个 
Rancher 管 理 的 IP 地 址 (10.42.0.0/16) ， 该 地 址 配置 在 缺 省 的 docker0 桥 上 . 通过 这 样 的 设置 ， 
在 同一 个 环境 里 的 所 有 容器 将 都 能 够 通过 “managed" 网 络 实现 路 由 可 达 fe 24033 问 。 


备注 :_Rancher 的 管理 IP 地 址 在 Docker meta-data 里 是 不 存在 的 ， 所 以 通过 Docker 
的 “inspect” 指 令 是 看 不 到 的 。 有 些 时 候 这 一 点 可 能 会 和 一 些 需要 Docker 桥 接 IP 地 址 的 工具 不 
兼容 。 我 们 正在 和 Docker 社 区 共同 合作 ， 确 保 Docker 的 未 来 版 本 更 清晰 地 支持 Overlay 网 络 。 


服务 发 现 


Rancher 采 用 标准 的 Docker Compose 规 范 来 描述 服务 ， 一 个 或 多 个 来 自 于 同一 个 Docker 镜 像 
的 容器 可 被 定义 为 一 个 基本 服务 。 在 同一 个 应 用 栈 里 ， 当 一 个 服务 (消费 者 ) 被 链接 到 另外 
一 个 服务 (生产 者 ) 时 ， 会 自动 产生 一 条 DNS 记录 ， amn 个 容器 的 实例 。 该 记录 使 得 服 
务 (生产 者 ) 能 够 被 访问 到 。 在 Rancher 中 创建 服务 的 其 它 益 处 包括 : 


e 服务 高 可 用 (HA) - 可 以 使 Rancher 来 自动 监控 容器 的 状态 ， 从 而 确保 服务 内 的 启动 的 容 
器 维持 在 预定 的 数量 。 

e 健康 检查 - 设 定 阅 值 ， 来 监控 容器 的 健康 状况 。 

e 添加 负载 均衡 器 - 为 服务 添加 一 个 基本 的 负载 均衡 器 ， 该 负载 均衡 器 使 用 HAProxy。 

© 添加 外 部 服务 - 可 以 添加 任意 的 IP 地 址 做 为 可 以 使 用 和 访问 到 的 服务 。 

e 添加 服务 别名 - 可 以 添加 一 条 DNS 记录 ， 使 得 服务 可 以 被 访问 到 。 


更 多 信息 ， 请 参考 添加 服务 , 添加 负载 均衡 器 , 添加 外 部 服务 或 者 添加 服务 别名 . 


负载 均衡 器 


Rancher 使 用 HAProxy 来 构建 一 个 被 管理 的 负载 均衡 器 ， 该 负载 均衡 可 Www | 多 台 主 
机 上 。 一 个 负载 均衡 器 可 用 lid 用 流量 分 配 到 多 个 单个 容器 里 ， 只 需要 将 这 些 容器 
添加 到 与 负载 均衡 器 相 链 接 的 服务 里 。 这 个 链接 到 负载 均衡 器 的 服务 ， o 动 注 
册 为 负载 均衡 的 目标 服务 


分 布 式 DNS 服务 


Rancher 本 身 内置 具 备 高 可 用 控制 引擎 的 轻 量 级 DNS 服务 ， 利 用 该 服务 ，Rancher 构 建 了 一 个 
式 DNS 服 务 。 每 个 健康 的 容器 被 链接 到 一 个 服务 或 者 被 添加 到 一 个 服务 别名 的 时 候 ， 该 

容器 会 被 自动 添加 到 DNS 记录 里 的 该 服务 中 。 当 查询 该 服务 名 时 ，DNS 服 务 会 返回 该 服务 中 
所 有 容器 的 随机 IP 列 表 。 


。 缺 省 情况 下 , 在 同一 应 用 栈 里 的 所 有 服务 不 需要 显 式 的 链接 定义 ， 就 会 被 添加 到 DNS 服务 
中 。 
o 你 可 以 通过 服务 名 称 来 解析 同一 应 用 栈 的 容器 地 址 。 
o 如 果 你 的 服务 需要 一 个 自 定义 的 DNS 名 称 ， 该 名 称 与 原 服 务 名 称 不 同 ， 你 将 需要 一 
个 链接 来 得 到 这 个 自 定 义 的 DNS 名 称 。 
o 对 负载 均衡 来 说 ， 仍 日 需要 链接 定义 才能 访问 到 目标 服务 
o 如 果 定 义 了 服务 别名 ， 和 链接 就 仍旧 pee ° 
o 如 果 想 使 得 在 不 同 应 用 栈 的 服务 可 以 被 解析 ， 你 需要 显 式 地 定义 链接 。 


因为 Rancher 的 覆盖 (overlay) 网 络 为 每 个 容器 定义 了 一 个 明确 的 IP 地 址 ， 你 不 需要 再 操心 
处 理 端 口 映射 ， 也 不 需要 处 理 类 似 同 一 服务 下 的 容器 使 用 不 同 的 端口 这 样 的 复杂 情况 。 这 
样 ， 利 用 一 个 基本 的 DNS 服 务 就 足 可 以 实现 服务 发 现 。 


健康 检查 


Rancher 构 建 了 一 个 完善 的 容器 健康 状况 监测 系统 。 该 系统 通过 在 多 个 主机 上 运行 的 网 络 代 
理 ， RARAZ EON AOFARAREE: REABRALNALHHAPON A 
应 用 的 健康 状态 。 当 一 个 容器 或 一 个 服务 定义 了 健康 检查 时 ， 每 个 容器 就 会 被 最 多 三 个 网 络 
代理 程序 来 监控 ， 这 些 网 络 代理 程序 运行 在 不 同 于 该 容器 父 节点 的 其 它 三 个 物理 节点 上 。 只 
有 当 至 少 一 个 HAProxy 的 实例 表明 健康 检查 "通过" 时， 该 容 rere 是 健康 的 。 


备注 : 一 个 例外 情况 是 ， 当 你 的 环境 里 只 包含 了 一 个 单一 的 主机 时 ， 健 康 检查 就 会 被 同一 
个 主机 节点 上 的 网 络 代 理 来 执行 。 


Rancher 的 去 中 心 化 的 健康 检查 模式 比 客户 端 模式 要 有 效 得 多 ， 另 外 ， 使 用 HAProxy 来 进行 健 
康 检 查 ， 那 些 原先 只 能 在 负载 均衡 器 定义 的 应 用 级 别 负载 均衡 策略 ， 都 可 以 在 服务 里 进行 定 
义 ， 从 而 实现 在 各 层次 上 去 监控 应 用 和 服务 的 健康 状况 。 


更 多 信息 ， 例 如 健康 检查 失败 的 不 同 场景 以 及 Rancher 如 何 显示 服务 ， 请 参考 健康 检查 . 你 也 
可 以 获取 更 多 信息 关于 如 何 通 过 使 用 rancher-compose 或 在 Ul 里 来 设置 健康 检查 . 


及 务 高 可 用 


Rancher 会 持续 地 监控 服务 里 容器 的 状态 ， 并 且 主 动 地 进行 管理 ， 确 保 服 务 保持 在 期 望 的 规 
模 。 当 健康 的 容器 数量 EE (或 者 甚至 多 ) HME > AAA AH AR 
发 动作 ， 局 动 (或 关闭 ) 容器 。 通 常 这 种 情况 是 由 于 一 个 节点 不 可 用 ， 一 个 容器 失败 或 者 容 


AS 


服务 没有 通过 健康 检查 。 


a 


服务 升级 


Rancher 支 持 服务 升级 的 概念 ， 该 功能 是 通过 允许 用 户 为 某 个 给 定 的 服务 来 使 用 负载 均衡 或 者 
应 用 服务 别名 来 实现 的 。 这 两 种 方式 ， 都 可 以 为 需要 该 服务 的 现 有 负载 关键 一 个 静态 的 目 

标 。 一 旦 该 设 定 建立 ， 某 个 底层 的 服务 可 以 被 Clone 为 一 个 新 服务 ， 通 过 隔离 的 测试 来 进行 校 
验 ， 当 就 绪 时 ， 通 过 负载 均衡 或 者 定义 服务 别名 的 方式 加 入 到 应 用 栈 。 而 原 有 的 服务 当 废 弃 

时 可 以 在 系统 中 删除 。 最 终 ， 所 有 的 网 络 或 应 用 流量 都 将 被 分 流 到 新 的 服务 。 


Rancher Compose 


Rancher 实 施 和 发 布 了 一 个 命令 行 工具 ， 该 工具 称 为 "rancher-compose”， 与 docker-compose 
的 命名 类 似 . 该 工具 可 以 引用 同样 的 docker-compose.yml 模 版 将 应 用 栈 在 Rancher 中 部 署 。 
Rancher-compose 的 工具 还 支持 rancher-compose.yml| 文 件 ， 该 文件 扩展 了 docker- 
compose.yml 的 定义 ， 允 许 定义 更 多 的 属性 ， 如 容器 规模 , 负载 均衡 策略 ， 健 康 检查 策略 以 及 
外 部 链接 等 ， 这 些 定义 目前 在 docker-compose 里 还 不 能 定义 . 


更 多 信息 , 请 参见 rancher-compose. 


应 用 栈 (Stacks ) 


Rancher 应 用 栈 与 docker 一 compose 所 定义 的 项 目 概念 类 似 。 它 代 表 着 一 组 服务 ， 来 构成 一 
个 典型 的 应 用 或 工作 负载 。 


oe 32.0 E 
ENE 
Rancher X74 & BERS > AM 5 Docker Swarm 兼容 的 模型 。 包括 如 下 策略 : 


e 端口 冲突 

e 共享 存储 卷 

. 主机 标签 

e 共享 网 络 栈 : --net=container:dependency 

o 严格 的 和 软 性 定义 的 亲 和 二 反 亲 和 规则 ， 这 些 规则 通过 使 用 env 变 量 (Swarm) 和 
label(Rancher) 来 定义 。 


另外 ，Rancher 支 持 调度 服务 触发 器 ， 人 允许 用 户 定义 特定 的 规则 ， 如 "添加 主机 ?或 "主机 标签 ” 
， 从 而 实现 自动 地 将 服务 扩展 到 具有 特定 标签 到 主机 上 。 


关于 如 何 调 度 容器 到 更 多 信息 ， 请 参考 如 何 使 用 UI 的 labels 和 调度 规则 或 者 如 何 使 用 labels 
in rancher-compose. 


Sidekicks 


Rancher 允 许 用 户 通过 定义 Sidekicks 来 定义 一 组 容器 ， 这 组 容器 和 主 容器 总 是 运行 在 同一 主 
机 节点 上 、 同 时 被 调度 以 及 同时 被 伸缩 。 一 个 服务 拥有 一 个 或 多 个 sidekick 容 器 ， 一 个 典型 的 
例子 是 用 来 在 多 个 容器 里 支持 存储 卷 (FP --volumes_from ) 和 网 络 (FP --net=container ) 的 定 
义 . 


更 多 信息 , 请 参考 sidekicks with rancher-compose. 


Rancher 基础 服务 


健康 检查 


Rancher 通过 在 它 的 主机 上 运行 托管 网 络 代理 端 实现 了 健康 监控 系统 用 来 协调 容器 和 服务 的 
分 布 式 健康 检查 。 这 些 网 络 代理 端 在 HAProxy 来 验证 你 的 应 用 的 健康 状态 。 当 无 论 
desa 容器 还 是 服务 的 健康 检查 被 开局 后 ， 每 个 容器 都 会 被 多 至 三 个 网 络 代理 端 所 监控 ， 代 理 

运行 于 不 同 于 容器 主机 的 主机 上 。 ae) 有 一 个 HAProxy 实例 汇报 “通过 ”的 健康 检查 ， 
容器 就 会 被 认为 是 健康 的 ， 当 所 有 HAProxy 实例 都 汇报 “不 健康 "的 健康 检查 ， 就 认为 容器 是 
不 健康 的 。 


主意 : 此 模式 仅 有 的 例外 情况 是 : 当 你 的 环境 中 仅 包含 一 个 单 主机 ， 在 这 种 情况 下 健康 检 
本 将 只 会 在 这 台 主 机 上 执行 。 


Rancher 处 理 网 络 区 分 并 且 那 比 基 于 客户 端的 健康 检查 更 有 效率 。 通 过 使 用 HAProxy 来 执行 
健康 检查 ，Rancher 允许 用 户 跨越 应 用 和 负载 均衡 来 指定 相同 的 健康 检查 策略 。 


注意 : 监控 检查 仅 对 使 用 托管 网 络 的 服务 有 效 。 如 果 你 选择 了 任何 其 他 的 网 络 选项 ， 它 将 
不 会 被 监控 。 


配置 


使 用 如 下 选项 来 配置 健康 检查 : 


Check type: 这 里 有 两 种 检查 - TCP Connection Opens ( 仅 确 认 端 口 打开 ) 和 HTTP 
Responds 2xx/3xx (执行 一 个 HTTP 请 求 并 确保 接受 了 正确 的 响应 )。 


HTTP request: 如 果 检 查 类 型 是 HTTP Responds 2xX/3xXX， 你 必须 指定 查询 的 URL 路 径 。 你 
能 选择 请 求 方法 ( GET, post , etc) 和 HTTP 版 本 ( HTTP/1.0 , HTTP/1.1 )。 


Port: 执行 检查 的 端口 。 

Check interval: 检查 执行 的 毫秒 数 间 隔 。 

Timeout: 在 一 次 无 回应 的 检查 超时 前 的 毫秒 数 。 

Healthy threshold: 在 容器 (当前 标记 为 非 健康 ) 被 再 次 认为 是 健康 前 成 功 的 检查 响应 次 数 。 


Unhealthy threshold: 在 容器 (当前 标记 为 健康 ) 被 认为 是 非 健康 前 失败 的 检查 响应 次 数 。 


失败 场景 


一 台 主 


响应 


所 有 激活 监控 此 容器 的 HAProxy 实例 将 会 侦 测 到 失败 并 标记 此 容器 为 " 非 健 
康 ”。 如 果 这 个 容器 是 一 个 服务 的 一 部 分 ，Rancher 将 会 通过 它 的 HA 功能 恢复 
此 服务 到 它 预定 义 的 数量 。 


当主 机 的 网 络 连接 丢失 ， 从 Rancher 服务 端 到 代理 端的 连接 也 会 丢失 。 当 代 
理 端 不 可 访问 ， 主 机 会 被 标记 为 "reconnecting"。 此 时 所 已 知 的 是 Rancher AR 
务 端 无 法 连 上 那 台 主机 的 代理 端 Rancher 中 的 健康 检查 针对 的 是 容器 本 身 而 
不 是 主机 ; 结果 是 ， 对 所 有 激活 的 HAProxy 实例 ， 容 器 都 不 可 达 。 如 果 这 个 
容器 是 一 个 服务 的 一 部 分 ，Rancher 将 会 通过 他 的 HA 功能 恢复 此 服务 到 它 预 
定义 的 数量 。 


当主 机 遭受 完全 失效 例如 电源 中 断 ， 从 Rancher 服务 端 到 代理 端的 连接 中 

断 。 当代 理 端 不 可 访问 ， 主 机 会 被 标记 为 "reconnecting"。 此 时 所 已 知 的 是 
Rancher 服务 端 无 法 连 上 那 台 主 机 的 代理 端 。Rancher 中 的 健康 检查 针对 的 是 
容器 本 身 而 不 是 主机 ; 结果 是 ， 对 所 有 激活 的 HAProxy 实例 ， 容 器 都 不 可 

达 。 如 果 这 个 容器 是 一 个 服务 的 一 部 分 ，Rancher 将 会 通过 他 的 HA 功能 恢复 
此 服务 到 它 预定 义 的 数量 。 


在 此 实例 中 ， 如 同 先前 的 案例 ， 从 Rancher 服务 端 到 代理 端的 连接 中 断 。 当 
代理 端 不 可 访问 ， 主 机 会 被 标记 为 "reconnecting"。 此 时 所 已 知 的 是 Rancher 
服务 端 无 法 连 上 那 台 主机 的 代理 端 。Rancher 中 的 健康 检查 针对 的 是 容器 本 身 
而 不 是 主机 ; 结果 是 ， 对 所 有 激活 的 HAProxy 实例 ， 容 器 都 不 可 达 。 如 果 这 
个 容器 是 一 个 服务 的 一 部 分 ，Rancher 将 会 通过 他 的 HA 功能 恢复 此 服务 到 它 
预定 义 的 数量 。 勘 误 : by alfredhuang211， 此 例子 中 ， 容 器 应 该 还 是 可 达 的 ， 
但 是 rancher 美 文 原文 仍然 写 的 是 不 可 达 ， 猜 测 不 知 是 撰写 错误 还 是 本 人 理解 
有 限 。 因 为 容器 可 达 ， 健 康 检查 仍然 可 以 通过 ， 认 为 容器 仍然 健康 。 


Rancher 内 部 DNS 服务 


在 Rancher 里 ， 我 们 有 自己 的 内 部 DNS 服务 ， 允 许 同一 个 cattle 环境 里 的 服务 能 解析 到 另 
外 任意 一 个 服务 


环境 里 的 所 有 服务 都 通过 <service_name> 被 解析 ， 并 且 不 需要 在 服务 间 建 立 连接 。 对 于 处 于 
不 同 栈 的 其 他 任何 服务 ， 你 需要 通过 <service_name>.<stack name 而 不 是 

<service_name> 。 如 果 你 想 要 使 用 不 同名 字 来 解析 服务 ， 你 能 设置 一 个 连接 ， 以 便服 务 能 够 
通过 服务 别名 解析 。 


十 连接 设置 服务 别名 
在 Ul 里 ， 当 添加 服务 时 , 展开 Service Links 部 分 ， 选 择 服 务 ， 提 供 别 名 


如 果 你 是 使 用 rancher -compose 来 添加 服务 ， docker-compose.yml 可 以 使 用 links 或 


external_links 指令 e 


servicel: 
image: wordpress 
如 果 另 外 的 服务 是 在 同一 个 应 用 堆栈 中 
links: 
# <service_name>:<service_alias> 
- Service2: mysal 
2 


LAA MEA A A db 
外 的 服务 去 在 不 引 的 应 用 堆栈 | 


external_links: 
# <service_name>:<service_alias> 
- service3:mysql 


从 容器 和 链接 


当 启 动 一 个 服务 ， 你 可 能 需要 服务 一 起 一 直 启 动 在 同一 主机 上 。 特 殊 用 例 是 当 试 图 使 用 另 一 
个 服务 的 volumes_from 或 net 。 当 无 论 是 通过 U| 还 是 使 用 rancher-compose 创 建 一 个 伙伴 
关系 ， 服 务 都 自动 通过 他 们 的 名 字 互 相 解 析 到 。 我 们 当前 不 支持 在 伙伴 服务 内 通过 链接 /外 部 
链接 创建 服务 别名 


当 创 建 伙 伴 关 系 ， 总 是 有 一 个 主 服务 和 若干 伙伴 服务 。 合 在 一 起 ， 他 们 被 认为 是 一 个 单独 的 
运行 配置 。 运 行 配 置 会 作为 一 组 容器 被 部 署 在 一 台 主 机 上 ， 主 服务 一 个 ， 另 外 每 个 伙伴 服务 
一 个 。 在 运行 配置 内 的 任何 一 个 服务 ， 你 都 能 通过 他 们 的 名 称 解 析 到 主 服务 或 者 伙伴 服务 

对 于 运行 配置 外 的 任何 服务 ， 主 服务 能 够 通过 名 字 解 析 到 ， 但 伙伴 服务 仅 能 通过 


<sidekick_name>.<primary_service_name> 解析 到 j 


容器 名 


所 有 的 容器 都 能 通过 他 们 的 名 字 被 全 局 解析 到 ， 因 为 每 个 服务 的 容器 名 在 每 个 环境 内 都 是 独 
一 无 二 的 。 不 需要 在 后 面 加 上 服务 名 或 栈 名 。 


le 


Ping 同一 栈 里 的 服务 
如 果 你 exec 进入 容器 的 shell， 你 能 通过 服务 名 ping 同一 栈 内 的 其 他 服务 
在 我 们 的 例子 中 ， 栈 名 为 stacka ， 带 有 两 个 服务 foo 和 bar ° 


在 exec 进入 foo 服务 的 一 个 容器 中 后 ， 你 能 ping bar 服务 


$ ping bar 

PING bar.stacka.rancher.internal (10.42.x.x) 58(84) bytes of data. 
64 bytes from 10.42.x.x: icmp_seq=1 ttl=62 time=1.63 ms 

64 bytes from 10.42.x.x: icmp_seq=2 ttl=62 time=1.13 ms 

64 bytes from 10.42.x.x: icmp_seq=3 ttl=62 time=1.07 ms 


Ping 不 同 栈 里 的 服务 
对 于 不 同 栈 内 的 服务 ， 过 使 用 <service_name>.<stack_name> ping 不 同 栈 内 的 服务 


在 我 们 的 例子 中 ， 我 们 有 一 个 栈 为 stackA ， 带 有 服务 foo ， 然 后 我 们 还 有 一 个 栈 为 
stackB ， 带 有 服务 bar ° 


如 果 我 们 exec 进入 服务 foo 的 一 个 容器 中 ， 你 能 通过 foo.stackB ping bar 服务 


$ ping bar.stackb 

PING bar.stackb (10.42.x.x) 56(84) bytes of data. 

64 bytes from 10.42.x.x: icmp_seq=1 ttl=62 time=1.43 ms 
64 bytes from 10.42.x.x: icmp_seq=2 ttl=62 time=1.15 ms 
64 bytes from 10.42.x.x: icmp_seq=3 ttl=62 time=1.27 ms 


Ping 伙伴 服务 


取决 于 你 从 哪个 服务 发 起 ping， 你 能 通过 <sidekick_name> 或 <sidekick_name>. 


<primary_service_name> 到 3 达 伙 伴 服 务 。 


在 我 们 的 例子 中 ， 我 们 有 一 个 栈 为 stacka > LER foo ， 带 有 伙伴 服务 bar ,还 有 个 服 
ZA hello 。 我 们 还 有 个 栈 为 stacks ° BAMA world ° 


N 


如 果 我 们 exec 进入 foo 服务 的 一 个 容器 ， 你 能 通过 他 的 名 字 直 接 ping bar 服务 。 


# Inside one of the containers in the “foo” service, which "bar is a sidekick to. 
$ ping bar 

PING bar.foo.stacka.rancher.internal (10.42.x.x) 56(84) bytes of data. 

64 bytes from 10.42.x.x: icmp_seq=1 ttl=64 time=0.060 ms 

64 bytes from 10.42.x.x: icmp_seq=2 ttl=64 time=0.111 ms 

64 bytes from 10.42.x.x: icmp_seq=3 ttl=64 time=0.114 ms 


如 果 我 们 exec HA hello 服务 的 一 个 容器 ， 在 同一 个 栈 内 ， 你 能 通过 foo ping foo AR 
务 ， 通 过 bar.foo ping bar 伙伴 服务 。 





在 `helL1o ”服务 中 的 一 个 容器 内 部 ， 它 不 属于 service/sidekick 服务 的 一 部 分 
# Ping the primary service (i.e. foo) 
$ ping foo 


PING foo.stacka.rancher.internal (10.42.x.x) 56(84) bytes of data. 
64 bytes from 10.42.x.x: icmp_seq=1 ttl=62 time=1.04 ms 
64 bytes from 10.42.x.x: icmp_seq=2 ttl=62 time=1.40 ms 
64 bytes from 10.42.x.x: icmp_seq=3 ttl=62 time=1.07 ms 
Ping the sidekick service (i.e. bar) 
$ ping bar.foo 
PING bar.foo (10.42.x.x) 56(84) bytes of data. 
64 bytes from 10.42.x.x: icmp_seq=1 ttl=62 time=1.01 ms 
64 bytes from 10.42.x.x: icmp_seq=2 ttl=62 time=1.12 ms 
64 bytes from 10.42.x.x: icmp_seq=3 ttl=62 time=1.05 ms 


如 果 我 们 exec HA world 服务 的 一 个 容器 ， 在 不 同 栈 内 ， 你 能 通过 foo.stacka ping foo 
服务 ， 通 过 bar.foo.stacka ping bar 伙伴 服务 。 


= 
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t Inside one of the containers in the world service, which is in a different st 

# Ping the primary service (i.e. foo) 

$ ping foo.stacka 

PING foo.stacka (10.42.x.x) 56(84) bytes of data. 

64 bytes from 10.42.x.x: icmp_seq=1 ttl=62 time=1.13 ms 

64 bytes from 10.42.x.x: icmp_seq=2 ttl=62 time=1.05 ms 

64 bytes from 10.42.x.x: icmp_seq=3 ttl=62 time=1.29 ms 
Ping the sidekick service (1.e. bar) 

$ ping bar.foo.stacka 

PING bar.foo.stacka (10.42.x.x) 56(84) bytes of data. 

64 bytes from 10.42.x.x: icmp_seq=1 ttl=62 time=1.23 ms 

64 bytes from 10.42.x.x: icmp_seq=2 ttl=62 time=1.00 ms 

64 bytes from 10.42.x.x: icmp_seq=3 ttl=62 time=0.994 ms 


从 任何 容器 ， 你 能 通过 他 们 的 名 字 ping 环境 内 的 其 他 容器 ， 而 不 用 管 他 们 是 否 在 不 同 栈 或 服 
务 内 。 


在 我 们 的 例子 中 ， 我 们 有 一 个 栈 为 stacka ， 包 含 服务 foo 。 我 们 还 有 个 栈 为 stackB ， 包 


A 5? Be em y R ; 
EMF bar ° 容器 的 名 字 是 <environment_name>_<service_name>_<number> ° 


如 果 我 们 exec HA foo 服务 的 一 个 容器 ， 你 能 ping bar 服务 内 的 容器 。 


$ ping stackB_bar_1 

PING stackB_bar_1.rancher.internal (10.42.x.x): 56 data bytes 
64 bytes from 10.42.x.x: icmp_seq=1 ttl=62 time=1.994 ms 

64 bytes from 10.42.x.x: icmp_seq=2 ttl=62 time=1.090 ms 

64 bytes from 10.42.x.x: icmp_seq=3 ttl=62 time=1.100 ms 


使 用 Route 53 做 外 部 DNS 


作为 Rancher catalog 的 一 部 分 ，Rancher 提供 了 a Route53 DNS 集成 的 DNS AR 
务 。 当 启动 这 个 服务 ， 有 一 个 route53 的 容器 被 启动 。 这 个 容器 会 监听 Rancer 元 数据 服务 器 
和 事件 ， 会 基于 元 数据 的 变化 更 新 DNS 记录 ， 并 更 新 到 Route53 服务 中 。 


最 住 实践 


e 在 您 部 署 的 Rancher 的 每 个 环境 中 ， 应 该 有 一 个 容器 数量 为 1 的 route53 服务 
e 2% Rancher 部 署 环境 应 该 不 能 共享 相同 的 hosted zone ° 


启动 Route53 服务 


点 击 Catalog 标签 ， 您 能 选中 Route53 DNS Stack。 
输入 一 个 名字， 输入 关于 这 个 堆栈 的 描述 。 
在 Configuration Options 中 ， 你 需要 提供 一 下 信息 : 


名 称 值 


AWS 
Access ”您 账户 AWS API 的 Access key 
Key 


AWS 
Secret 您 账户 AWS API 的 Secret key 
Key 


AWS AWS 的 Region 名 。 我 们 建议 选择 离 您 所 地 最 近 的 区 。 更 新 的 信息 将 会 被 发 送 
Region ”到 该 AWS API 端点 ，Rancher Route53 会 随时 及 时 更 新 DNS 更 新 请 求 。 


Hosted 


Zone Route53 的 hosted zone。 这 个 zone 需要 提前 创建 好 。 


在 填写 了 这 些 字段 后 ， 点 击 Create 按 钮 。 堆 栈 将 被 创建 出 来 带 有 route53 的 服务 ， 而 您 只 
需要 做 启动 这 个 服务 即 可 。 


使 用 Route53 服务 


这 个 route53 服务 只 会 在 服务 有 端口 暴露 在 主机 上 时 ， 来 未 知 生 成 DNS 记录 。 对 于 每 一 个 
Rancher 生成 的 DNS 记录 ， 它 会 按 下 面 的 形式 创建 出 fqdn : 


fadn=<serviceName>.<stackName>.<environmentName>.<yourHostedZoneName> 


在 AWS 的 Route 53 上 ， 把 以 Record Set 的 形式 被 表达 : name=fqdn 和 value=[ 服 务 被 部 署 
的 主机 的 IP 地 址 。 Rancher routes3 服务 将 只 管理 以 . 结尾 的 Record Set， 默 认 的 300 
秒 。 


一 旦 在 AWS 的 Route 53 里 配置 了 DNS 记录 ， 被 创建 的 fqdn 记录 将 被 传 回 Rancher， 会 被 
配置 在 service.fqdn 字段 。 您 能 通过 点 击 服 务 的 View in API 下 拉 菜 单 后 ， 搜 索 找到 fqdn 找 
到 对 应 的 fgdn 记录 。 


当 在 浏览 器 中 使 用 farn 时 ， 它 会 被 指向 服务 中 的 一 个 容器 中 。 如 果 一 个 服务 中 容器 的 IP 地 
址 会 有 任何 变化 ， 这 些 变化 将 也 被 更 新 到 AWS Route 53 服 务 中 。 而 从 用 户 使 用 fqdn 域名 访 
问 服务 的 角度 看 ， 则 不 会 体验 到 有 任何 变化 。 


注意 : 在 route53 服务 启动 了 以 后 ， 对 于 已 经 部 署 了 的 有 主机 端口 的 服务 将 也 会 得 到 一 
个 fqdn ° 


删除 Route53 服务 


当 从 Rancher 中 删除 了 routes3 服务 之 后 ，Amazon Route 53 中 的 Record Set 将 不 会 被 自 
动 删除 。 它 们 还 是 需要 登录 了 您 的 Amazon AWS 账号 之 后 再 手工 删除 掉 。 


为 外 部 DNS 使 用 特定 的 IP 


默认 ，Rancher DNS 所 使 用 的 主机 IP， 是 注册 到 Rancher o 这 里 会 有 这 样 一 
种 用 例 ， 被 配置 在 Rancher 中 的 主机 使 用 私有 网 络 通信 ， 而 这 个 主机 将 需要 通过 外 部 DNS 
使 用 公 网 IP 来 对 外 暴露 服务 。 在 这 种 情况 下 在 你 需要 制 on DNS 所 使 用 的 IP， 您 需要 在 
使 用 外 部 DNS 服务 前 为 主机 添加 主机 标签 。 


在 你 启动 外 部 DNS 服务 之 前 ， 请 添加 下 面 的 主机 标签 。 标 签 的 值 是 Rancher 的 Route 53 AR 
务 会 用 到 的 。 如 果 没 有 设置 这 个 标签 的 话 ，Rancher 的 Route53 DNS 服务 器 就 会 直接 使 用 主 
机 IP。 


io.rancher.host.external_dns_ip=<IP_TO_BE_USED_FOR_EXTERNAL_DNS> 





元 数据 服务 


Martin 初始 化 版 本 翻译 中 ， 欢 迎 随 后 review 


使 用 Rancher 的 元 数据 服务 ， 你 能 在 任意 Rancher 所 管理 的 何 容 器 内 部 来 查询 到 mee 容器 所 
管理 的 网 络 和 的 相关 信息 。 元 数据 可 以 涉及 到 容器 自身 、 所 在 服务 或 者 堆栈 ， 以 及 容器 所 人 允 
许 的 主机 ， 等 等 。 元 数据 默认 格式 是 JSON © 


容器 可 以 通过 以 下 几 种 方式 在 Rancher 管理 的 网 络 上 启动 。 


e 通过 图 形 界面 UI, 一 个 服务 /容器 被 启动 时 使 用 了 Managed 网 络 参数 。 默 认 情 况 下 ， 服 
务 网 络 已 经 被 设置 为 Managed 。 
e 通过 Rancher-Compose 命令 行 ， 一 个 服务 /容器 ， 当 没有 被 设置 为 网 络 模式 net )> A 
Rancher 管理 的 网 络 上 被 启动 。 
e 当 用 docker 原生 命令 BABE, 如 果 你 在 docker run 命令 中 加 入 标签 
io.rancher.container.network=true ， 这 样 容器 就 加 入 了 Rancher 的 管理 网 络 。 
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: 元 数据 服务 对 于 Rancher 的 系统 容器 是 
hoor 容器 。 


可 用 的 ， 如 : Network Agent 和 LB 


如 何 获取 到 元 数据 


在 Rancher 的 图 形 界面 上 ， 您 能 从 容器 的 下 拉 菜 单 Execute Shell 上 进入 到 容器 的 命令 行 。 
下 拉 菜 单 在 鼠标 滑 过 容器 的 时 候 可 以 出 现 。 


你 可 以 使 用 curl 命令 来 过 去 元 数据 。 
# ER curl 没有 安装 ， 安 装 它 
$ apt-get install curl 


# curl 命令 可 以 返回 纯 文本 的 相应 结果 
$ curl http://rancher-metadata/<version>/<path> 


访问 路 径 依赖 于 你 想 访问 什么 样 元 数据 和 想得到 的 相应 结果 的 格式 。 


ven 
> 
PX 


self/container 


器 y 


self/service 


Pr SS DE DY) 


PAS 


self/stack 


we SE Se 


self/host 


Sh RQ A SM A 


containers 


as Oo} Re 


services 


P FS OG) 


stacks/<stack- 
name> 


SE TE oh) Re 


元 数据 的 版 本 


描述 


提供 的 元 数据 是 您 执行 元 数据 查询 命令 的 容器 自身 的 信息 


提供 的 元 数据 是 您 执行 元 数据 查询 命令 的 容器 所 属 服务 的 信息 
提供 的 元 数据 是 您 执行 元 数据 查询 命令 的 容器 所 属 堆栈 的 信息 
提供 的 元 数据 是 您 执行 元 数据 查询 命令 的 容器 所 运行 于 主机 的 
zh 


lo 。 用 纯 文 本 格式 ， 它 可 返回 了 所 有 


元 数据 信 息 。 使 用 索引 发 者 容器 名 称 在 路 径 中 > 你 可 以 获取 特 
定 容器 的 元 数据 o 


提供 所 有 其 它 服 务 的 元 数据 。 用 纯 文 本 格式 ， 能 返回 所 有 服务 
的 索引 编号 。 用 JSON 格式 ， 它 能 返回 所 有 服务 的 元 数据 信 
息 。 在 路 径 中 使 用 索引 编号 或 者 名 称 ， 可 以 获得 一 个 特定 服务 
的 元 数据 信息 。 如 果 去 查看 容器 相关 信息 ， 在 V1 ( 2015-07-25 ) 
中 只 能 返回 容器 的 名 称 ， 而 在 V2 ( 2015-12-19 ) 中 则 可 以 容器 对 
象 清单 。 


提供 所 有 其 它 堆栈 的 元 数据 。 用 纯 文本 格式 ， 能 返回 所 有 堆栈 
的 索引 编号 。 用 JSON 格式 ， 它 能 返回 所 有 堆 柜 的 元 数据 信 
息 。 人 索引 编号 或 者 名 称 ， 可 以 获得 一 个 特定 堆栈 
的 元 数据 信息 。 如 果 去 查看 容器 相关 信息 ， 在 V1 ( 2015-07-25 ) 
中 只 能 返回 回 容器 的 名 称 ， 而 在 V2 ( 2015-12-19 ) 中 则 可 以 容器 对 
象 清单 。 


在 curl 命令 里 我 们 强烈 建议 使 用 一 个 的 定 的 版 本 ? 而 不 总 是 使 用 latest ° 


注意 : 我 们 对 latest 版 本 会 持续 更 改 ， 不 同 版 本 返回 的 数据 可 能 不 同 ， 因 此 可 能 会 影响 
到 您 的 代码 的 兼容 性 。 


元 数据 服务 的 版 本 是 基于 日 期 的 。 
版 本 参考 版 本 
V2 2015-12-19 
V1 2015-07-25 


版 本 的 差异 
V1 vs. V2 


当 使 用 路 径 /services/<service-name>/containers 或 </stacks/<stack- 
name>/services/<service-name>/containers 查看 容器 元 数据 信息 时 ，V1 返回 容器 的 名 称 ， 而 
V2 返回 所 有 容器 对 象 。 元 数据 服务 的 V2 版 本 可 以 提供 更 多 信息 。 

实例 

在 Rancher 中 id 有 一 个 堆栈 名 为 foostack ° © 包含 一 个 由 三 个 容器 组 成 的 名 为 


barservice 的 服 务 e 


# 使 用 V1 返回 的 只 是 服务 的 容器 名 称 

$ curl --header 'Accept: application/json' 'http://rancher-metadata/2015-07-25/service 
s/barservice/containers' 

["foostack_barservice_1", "foostack_barservice_2", "foostack_barservice_1"] 


# 使 用 V2 返回 的 是 服务 中 所 有 容器 对 象 

$ curl --header 'Accept: application/json' 'http://rancher-metadata/2015-12-19/service 
s/barservice/containers' 

[{"create_index":1, "health_state":null, "host_uuid":... 


# 服务 里 所 有 容器 的 元 数据 清单 

3] 
# 使 用 V2， 你 能 详细 查看 某 个 特定 容器 对 象 
$ curl --header 'Accept: application/json' 'http://rancher-metadata/2015-12-19/service 
s/barservice/containers/foostack_barservice_1' 
Eeoreateaumndex 7, zunealehestagelinull hosteuund ner 

务 里 所 有 容器 的 详细 信息 清单 

3] 
# 使 用 /stacks/< 服 务 - 名 称 >， 你 能 详细 查看 服务 和 容器 
# 使 用 V1 只 能 返回 服务 中 容器 的 名 称 
$ curl --header 'Accept: application/json' 'http://rancher-metadata/2015-07-25/stacks/ 
foostack/services/barservice/containers' 
["foostack_barservice_1", "foostack_barservice_2", "foostack_barservice_1"] 
# 使 用 V2 能 返回 服务 中 所 有 容器 对 象 详情 清单 
$ curl --header ie application/json' 'http://rancher-metadata/2015-12-19/stacks/ 
foostack/services/barservice/containers' 
[iicreate=index 17,2 heablthEstace mul nos tau Udall i. 


务 里 所 有 容器 的 详细 信息 清单 


3] 


纯 文本 vs JSON 格式 


元 数据 信息 能 返回 成 纯 文 本 合作 和 JSON 格式 。 基 于 你 怎样 使 用 元 数据 的 需求 ， 你 能 选择 任 
意 格式 。 


纯 文 本 


curl 命令 时 ， 您 会 从 所 请 求 的 路 径 中 获得 纯 文 本 。 你 可 以 从 路 径 的 最 顶级 开始 查询 ， 
根据 返回 的 可 用 的 键 值 信息 继续 向 下 层 访 问 ， 直 到 元 数据 服务 返回 了 您 想 查 询 的 数据 。 
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$ curl 'http://rancher-metadata/2015-12-19/self/container' 
create_index 

health_state 

host_uuid 

hostname 

ips/ 

labels/ 

name 

ports/ 

primary_ip 

service_name 

stack_name 

start_count 

uuid 

$ curl 'http://rancher-metadata/2015-12-19/self/container/name' 
# ER: Curl 不 能 换行 ， 因 此 最 后 一 行 的 返回 值 和 命令 提示 符 出 现在 同一 行 行 。 
Default_Example_1$root@<container_id> 

$ curl 'http://rancher-metadata/2015-12-19/self/container/label/io.rancher.stack.name' 
Default$root@<container_id> 

# 数组 可 以 通过 索引 号 和 名 称 来 返回 值 

$ curl 'http://rancher-metadata/2015-12-19/services' 
O=Example 

# 你 可 以 在 路 径 中 使 用 索引 号 或 者 名 称 

$ curl 'http://rancher-metadata/2015-12-19/services/0' 

$ curl 'http://rancher-metadata/2015-12-19/services/Example' 


JSON 
把 Accept: application/json 添加 在 curl 命令 的 请 求 标记 中 ， 可 以 返回 JSON 格式 的 数据 。 


$ curl --header 'Accept: application/json' 'http://rancher-metadata/2015-12-19/self/co 
ntainer' 

$ curl --header 'Accept: application/json' 'http://rancher -metadata/2015-12-19/self/st 
ack' 

# 返回 某 个 堆栈 总 其 它 服务 的 元 数据 

$ curl --header 'Accept: application/json' 'http://rancher-metadata/2015-12-19/service 


s/<service-name>' 
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create_index 


health_state 
host_uuid 
hostname 

ips 

labels 


name 
ports 


primary_ip 
service_index 
service_name 
stack_name 
start_count 


uuid 


服务 


描述 
在 服务 里 容器 被 启动 的 顺序 编号 ， 例 如 : 2 意味 着 它 应 该 是 在 服务 中 第 
二 个 被 启动 的 。 注 意 ; Crete index 是 不 会 被 重复 使 用 的 。 如 果 您 的 服 
务 有 两 个 容器 E, 当 你 删除 了 第 二 个 容器 BE ， 下 一 个 被 局 ae 器 得 到 
的 create_index 编号 是 3， 尽 管 共 只 有 2 个 容器 


如 果 健康 检查 被 启用 用 了 ， 这 是 容器 健康 状态 信息 。 

Rancher 服务 器 分 配给 主机 的 唯一 识别 标识 。 

容器 的 主机 名 。 

当 多 网 卡 被 支持 了 ， 它 将 显示 IP 地 址 清单 。 
容器 上 的 标签 清单 。 标 签 的 格式 是 key! value ° 


容器 内 使 用 的 端口 清单 . 端口 的 格式 


col 2 


容器 所 在 的 服务 的 编号 

服务 的 名 字 (如 果 存 在 ) 
服务 所 在 的 堆栈 的 名 字 (如 果 存 在 ) 
容器 被 自动 的 次 数 。 


Rancher 分 配给 容器 的 唯一 标识 。 


FR dei 


containers 服务 中 容器 的 名 称 清 单 。 


Create_index of the last container created of the service. Note: 
Create_index is never reused. If you had a service with 2 containers 
create_index and deleted the 2nd container, the create_index will be 2. The next 
container that gets launched for the service would update the 
create_index to 3 even though there are only 2 containers. 


expose 


external_ips | 外 部 服务 的 外 部 IP 地 址 清单 


fqdn 服务 的 FQDN 全 域名 
hostname 外 部 服务 的 CNAME 
kind Rancher 服务 的 类 型 
labels 服务 上 的 标签 清单 。 标 签 的 格式 是 key: value . 


所 连接 的 服务 。 连接 的 格式 是 


stack_name/service_name:service_alias ° links 会 显示 所 有 的 键 值 


(例如 : Ea 14 140) 4012 01 [E 
你 会 需要 继续 向 下 查看 来 找到 特定 的 键 值 。 

metadata 用 户 添 加 的 元 数据 

name 服务 的 名 称 

se 在 服务 中 所 使 用 的 端口 . 端口 的 格式 是 

hostIP:publicIP:privateIP[/protocol] ° 

scale 服务 的 数量 

sidekicks sidekicks 的 服务 名 清单 

stack_name 服务 所 在 的 堆栈 的 名 称 

uuid Rancher 分 配给 服务 的 唯一 标识 


堆栈 


字段 描述 
environment_name 堆栈 所 在 环境 的 名 称 
name 堆栈 的 名 称 
services 堆栈 中 的 服务 的 清单 
uuid Rancher 分 配给 堆栈 的 唯一 标识 。 


x 


主机 


FR 首 述 


agent_ip Rancher Agent 的 IP 地 址 ， 例 如 : CATTLE_AGENT_1P 环境 变量 的 值 。 
hostId 在 某 个 环境 中 主机 的 唯一 标识 

labels 主机 标签 清单 。 标 签 格式 是 key:value 

name 主机 名 称 

uuid Rancher 分 配给 主机 的 唯一 标识 


给 服务 添加 用 户 元 数据 


Rancher 可 以 让 用 户 给 服务 增加 自己 的 元 数据 。 目 前 ， 这 个 功能 只 能 通过 rancher-compose 
来 实现 ， 并 且 元 数据 需要 是 rancher-compose.yml 文件 的 一 部 分 。 在 metadata 键 里 ，yaml 
将 被 解析 为 JSON 格式 用 于 元 数据 服务 。 


rancher -compose.yml 示例 


service: 
# Scale of service 
scale: 3 
# User added metadata 
metadata: 
example: 
name: hello 
value: world 
example2: 
foo: bar 


在 这 个 服务 启动 之 后 ， 你 可 以 通过 元 数据 服务 找到 这 个 信息 在 .../self/service/metadata 或 


者 .../services/<service_id>/metadata 中 = 


JSON 查询 


$ curl --header 'Accept: application/json' 'http://rancher-metadata/latest/self/servic 
e/metadata' 
{"example":{"name":"hello", "value":"world"}, "example2":{"foo":"bar"}} 


Plaintext #74 


a 


数据 服务 


we 
PC 


$ curl 'http://rancher-metadata/latest/self/service/metadata' 


example/ 


$ curl 'http://rancher-metadata/latest/self/service/metadata/example' 


name 
value 


$ curl 'http://rancher-metadata/latest/self/service/metadata/example/name' 


# Note: Curl will not provide a new line, 
command prompt 
hello$root@<container_id> 


so single values will be on same line as the 
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存储 服务 


Alan A > Yo 


Storage Service 


In the Rancher catalog, Rancher provides storage services that are capable of exposing 
volumes to containers. Currently, the storage services are pre-fixed with Convoy in the 
catalog. 


Prerequisites «You have the underlying storage system properly deployed and accessible to 
Rancher services 


Limitations «Only one Convoy stack can be deployed once per one Rancher environment. 
«Users are able to create service/containers and models exactly the same behavior as if you 
deployed a container using native Docker 1.10.3 commands. When creating a new 
container, the following rules apply: elf the volume name (e.g. foo:/path/in/container) is 
specified with a driver name (e.g. Convoy-Gluster), the container will be deployed on one of 
the hosts that belong to the Convoy-Gluster Storage Pool with a new volume "foo" created. 
olf the volume name (e.g. foo:/path/in/container) is specified with or without a driver name 
and "foo" exists in Rancher, the container will be launched on a host from that Storage Pool 
that has access to "foo". «If the volume name (e.g. foo:/path/in/container) is specified with 
NO driver name and "foo" DOES NOT exist in Rancher, it will be created as a local disk 
volume for that container. At this point, normal scheduling rules apply. 


Setting up the Storage Service 
From the Catalog tab, select one of the Convoy services. 


By default, we've auto-populated the required fields. Edit the fields to your desired choices. 
After filling in the form, click on Create. 


Viewing Storage Pools 


After your storage service has been launched, a storage pool has been created and is 
viewable in Infrastructure -> Storage Pools. You will be able to see all the Convoy storage 
services that are running in your environment. The name of the storage pool is derived from 
the name of the stack. 


In each storage pool, the hosts that have the storage service running will be listed. Besides 
the list of hosts, the lists of volumes used in the storage pool is also listed. For each volume, 
you can see the name of the volume (i.e. the name of the volume on the host(s)), and the 
mounts of each volume. For each mount, there is the container name and the directory path 
inside the container. 


Using the Storage Service in the Ul 


After your storage service has been launched, a storage pool has been created and is 
viewable in Infrastructure -> Storage Pools. Services can start using the shared storage. In 
the Volumes tab, provide a volume and a volume driver. The volume will be in the same 
syntax as Docker, :</path/in/container> . Docker volumes default to mount in read-write 
mode, but you can set it to be mounted read-only by adding the :ro at the end of the volume. 
The volume driver will be the name of the storage pool, that was created after launching the 
Convoy storage service. 


Using the Storage Service with Rancher-Compose 


After the storage service has been launched, you can start using the storage service as a 
volume_driver in the docker-compose.yml . The volume_ driver would be the name of the 
storage pool. 


test: tty: true image: ubuntu: 14.04.3 stdin_open: true volumes: 
e volume_name_on_host:/path/in/container volume_driver: 
Adding Volumes to Storage Pools 


A volume can be added to a storage pool with two methods: 1.Upon starting a service that 
has a volume and a volume driver, that is the storage service. When the service is started, 
the volume is created on all hosts and mounted in all containers. The volume is also added 
to the storage pool in Rancher. 2.In Infrastructure -> Storage Pools, click on Add Volume. 
Provide the name of the volume for the specified storage pool. 


Example using GlusterFS 


In this example, we're going to provide an example of how to use GlusterFS to have a 
shared storage across hosts. 1.Launch Gluster FS -In the Catalog tab, click on View Details 
of the Gluster FS service. lf desired, edit the Name of the stack for Gluster FS and add a 
description. «In the Configuration Options, edit the volume name. By default, Rancher has 
given the volume name my_vol . «Click on Launch to start the Gluster FS service. This will 
take a minute or two. You will be able to view the services in Applications -> Stacks. 


2.Launch Convoy Gluster «ln the Catalog tab, click on View Details of the Convoy Gluster 
service. 


olf desired, edit the Name of the stack for Convoy Gluster and add a description. «In the 
Configuration Options, edit the Volume Name, if you have changed the volume name while 
launching the Gluster FS service. «Select the Gluster FS service that is running in Rancher. 
The service is named glusterfs-server . «Click on Launch to start the Convoy Gluster service. 
The convoy-gluster service will be deployed on every host. You will be able to view the 
services in Applications -> System. eCheck that the storage pool ( convoy-gluster ) has been 
created in the Infrastructure -> Storage Pools tab. Note: The name of the storage pool is 
derived from the name of the stack. 


3.Launch Service using the Convoy Gluster service -Click on Add Service in a different 
stack. Set up your service as you typically would. mFor this example, I'll be using the 
ubuntu: 14.04.3 image to provide how the storage service is working and a scale of 10. 


In the Volumes tab, add the name of your volume. The naming convention of the volume 
will be the same as Docker, :</path/in/container> . Docker volumes default to mount in read- 
write mode, but you can set it to be mounted read-only by adding the :ro at the end of the 
volume. mFor this example, | have used glustervol1:/testvolume as the volume name. 


In the Volumes tab, the Volume Driver will be the name of the storage pool that was 
created. -Click on Create to create your service. After the service is created, start the 
service. 


4.Checking that the Services across Hosts are sharing volumes eln the detailed page of your 
service, you can see all the containers launched on different hosts. «Select a container on 
one of the hosts and use the container's dropdown to select Execute Shell. In the container, 
check that the directory that you had set in the service creation exists. Create a file in the 
shared volume directly. 


$ cd testvolume $ vi test.yml $ Is test.yml «Select a container on a different host and use the 
container's dropdown to select Execute Shell. In the container, check that the directory and 
file that was created in the previous container exists. 


$ cd testvolume $ Is test.yml 


5.Checking the Volume Driver on the Host «Use docker volume Is to view the list of Docker 
volumes. One of the entries will be using the convoy_gluster driver with the volume name 
that was created in the service. In my example, glustervol1 will be listed. 


审计 有 总 
只 有 管理 者 才能 存 取 审 计 日 志 。 你 可 以 在 Admin -> Audit Log 找到 审计 日 志 。 
Rancher 的 审计 日 志 是 集合 了 不 同类 型 的 事件 。 
e ATAR api 调用 我 们 的 API 时 。 这 个 事件 将 会 记录 谁 执行 这 个 动作 和 怎么 调用 这 个 
API (例如 : 透 过 用 户 界 面 、 透 过 API key) 
e 其 他 的 有 让 Rancher AR 43% 2) 4 m AA 260 api 事件 。 例 如 实例 在 一 个 服务 的 容器 在 
处 理 过 程 ， 会 记录 在 instance.create 事件 中 。 


系统 配置 


本 文档 首 稿 正在 编辑 中 ， 请 随后 帮忙 review ° 
访问 控制 
Access Control 


What is Access Control? 


The first account that authenticates with Rancher will become the admin of the account. For 
more information, see permissions of an admin. 


Enabling Access Control 


In the Admin tab, click Access Control. 


Currently, Rancher supports three methods of authentication: Active Directory, GitHub, Local 
and OpenLDAP. After authenticating your Rancher instance, Access Control will be 
considered enabled. With Access Control enabled, you will be able to manage different 
environments and share them with different groups of people. 


When Access Control is enabled, the API is locked and requires either being authenticated 
as a user or by using an AP! key to access it. 


Active Directory 


Select the Active Directory icon. If you want to use Active Directory using TLS, ensure that 
you have started Rancher server with the appropriate certificate. Fill in the sections and 
authenticate Rancher by clicking Authenticate. When Active Directory is enabled, you'll 
automatically be logged in as the username that was authenticated. You will also be logged 
in as an admin of Rancher. 


GitHub 


Select the GitHub icon and follow the directions in the Ul to register Rancher as a GitHub 
application. After clicking Authenticate with GitHub, Access Control is enabled and you are 
automatically logged into Rancher with your GitHub login credentials and as an admin of 
Rancher. 


Local Authentication 


Local authentication allows you to create your own set of accounts that is saved in the 
Rancher database. 


Select the Local icon. Create an admin user by providing the Login Username, Full Name, 
and Password. Click Enable Local Auth to turn on local authentication. By clicking this 
button, the admin is created and saved in the database. You are automatically logged into 
the Rancher instance as the admin account that was just created. 


OpenLDAP 


Select the OpenLDAP icon. If you want to use a OpenLDAP using TLS, ensure that you 
have started Rancher server with the appropriate certificate. Fill in the sections and 
authenticate Rancher by clicking Authenticate. When OpenLDAP is enabled, you'll 
automatically be logged in as the username that was authenticated. You will also be logged 
in as an admin of Rancher. 


Site Access 


Anyone who is a member or owner of an environment will also have access to the Rancher 
instance. Alternatively, you can invite members to access the Rancher instance, but when 
they log in, they will have their own environment. These members, who are added by using 
Access Control or Accounts options, will not be able to see other environments until they 
are added as a member to them. 


Anyone with the permissions to view the Rancher instance will be given user permissions. 
However, they will not be able to view the Admin tab. In order for users to view different 
environments, they will need to be added by an owner to the environment. 


Active Directory/OpenLDAP 


Once Active Directory or OpenLDAP is enabled, any user will be able to access the Rancher 
site. Eventually, we will be adding in the ability to restrict the Rancher instance to specific 
users and group members. Rancher still has environments to keep resources protected from 
other users and groups, but anyone part of your LDAP server will be able to access the 
Rancher instance. 


GitHub 


If you wanted to add users to Rancher without sharing your environment, you can add them 
in the Site Access section. Click the Customize button. 


Option 1: Allow any GitHub user 
This would allow anyone with a GitHub account to access your site. 
Option 2: Restrict to specific GitHub users and organization members 


By clicking the drop-down menu icon next to the + button, you'll see the list of organizations 
that you are a member of. When you click any of those organizations, Rancher adds their 
name to the list of Authorized Users and Organizations. You can also add individual users by 
typing in their username into the text box and clicking the +. This will just add the 
users/organizations to the list, but you will still need to save! 


Note: Save your configuration! For either option, you must click the Save 
authorization configuration button in order for any changes to take affect. If you leave 
the page before saving, your changes will be lost. 


Local Authentication 


Once local authentication is enabled, the admin can create additional admins/users by 
accessing the Admin > Accounts tab. Click Add Account and fill in the details of the 
account you want to add. You can select their account type as an Admin or User. An admin 
has the ability to view the Admin tab while users of Rancher instance would not have the 
visibility to the tab. 


Once an account has been created, the admin/user can be added to any environments. 


Account Types 


The account type determines whether or not an account will have access to the admin tab. 
For each environment in Rancher, there are membership roles that provide different level of 
access for a specific environment. 


Admin 


The first user that authenticates Rancher becomes an admin of Rancher. Only admins will 
have permissions to view the Admin tab. This includes the ability to configure Access 
Control, Accounts, Settings, and Processes. 


When managing environment, admins have the ability to view all the environments in 
Rancher even if the admin is not added as a member to the environment. In an admin's 
environment drop-down menu, the members will only see the environments that they are on 
the membership list. 


Admins can add other users to be an admin of Rancher. They can change a user's role on 
the Admin > Accounts page after the user has logged into Rancher. In the Admin > 
Accounts tab, click Edit next to the account name and change the account type to Admin. 
Click Save. 


Users 


Besides the user that authenticates Rancher, any other user will automatically be added with 
user permissions. They will not be able to see the Admin tab. 


They will only be able to view the environments that they are members of. 


Disabling Access Control 


If you decide that you no longer want Access Control, click the Disable access control 
button. This will make your Rancher instance open to the public and anyone can access 
your API. This is not recommended. 


设置 


In the Admin -> Settings page of Rancher, we allow customization of Rancher for different 
areas of the product. 


Host Registration 


Before launching any hosts, you will be asked to complete the host registration. This 
registration sets up how your Rancher server is going to connect with your hosts. If you have 
already set up access control, you will not be prompted to set host registration as Rancher 
assumes that your URL will be accessible. 


The setup determines the base URL your hosts will use to connect to the Rancher API. By 
default, Rancher selects the base URL you used to access the Ul. If you choose to change 
the address, make sure to specify the port that should be used to connect to the Rancher 
API. If you are configuring Rancher with SSL, be sure to change the protocol to https . This 
registration setup determines what the command will be for adding custom hosts. 


If access control is turned on for Rancher, only the admin will be able to change the host 
registration. By default, the first admin is the first user to authenticate with Rancher when 
access control was configured. If access-control is still not configured, any users to the site 
can update the host registration. This option can be updated in the Admin -> Host 
Registration tab. 


Catalog 


By default, the catalog is enabled with two catalogs, the certified templates from the official 
Rancher Catalog and the community-catalog. You can select to enable or disable these 
catalogs. 


An admin has the ability to add private catalogs to Rancher. Adding a catalog is as simple as 
adding a catalog name and the git URL. The correct format of the git URL can be found 
here. Whenever you add a catalog, it will be immediately available in the catalog. 


If you want to create your own private catalog to add, the git repository must be set up in a 


specific format. 


Machine Drivers 


Docker-machine drivers can be added into Rancher to add hosts. 


Adding Machine Drivers 


Click on Add Machine Driver. 


1. 


4. 


Provide a name for the driver to be displayed when adding [other 
hosts]/rancher/rancher-ui/infrastructure/hosts/other/). 

Provide the Download URL. This URL is the machine driver binary 64-bit Linux. 
(Optional) Provide the MD5 Checksum to verify the downloaded driver matches the 
expected checksum. 

When complete, click Create. 


After clicking on create, Rancher add the additional driver and will display this option in the 


Driver field of adding [other hosts]/rancher/rancher-ui/infrastructure/hosts/other/). 
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环境 


API 8 Keys 


点 击 API 以 便 找 到 API 端点 。 每 当 你 创建 了 一 个 工作 环境 的 API key > 42447 URL 端点 都 会 
将 你 指向 你 当前 正在 操作 的 那个 环境 . 


如 果 权 限 控制 未 配置 ， 任 何 知 道 I|P 地 址 的 人 都 拥有 访问 你 的 Rancher API 的 权限 。 高 度 建 议 局 
用 权限 控制 管理 。 


一 旦 启用 了 权限 控制 并 且 未 登录 ， 对 每 个 环境 均 需 要 创建 一 个 工作 环境 API key， 以 便 API 能 
访问 指定 的 工作 环境 。 


在 Rancher 里 ， 通 过 点 击 对 象 的 下 拉 菜 单 中 的 View In API ， 所 有 的 对 得 都 能 通过 AP| 来 查 
看 。 在 创建 环境 API key 时 提供 的 URL 端点 ， 同 样 提供 了 到 API 各 个 部 分 的 全 部 链接 。 点 击 
此 处 了 解 更 多 关于 如 何 使 用 API 


添加 环境 API Keys 


在 添加 任何 环境 API key 之 前 ， 请 确认 你 在 正确 的 环境 中 。 点 击 Add Environment API 

Key > 提供 Name ， 并 根据 需要 ， 卉 写 Description。 点 击 Create。Rancher 将 会 生成 并 显 
示 你 的 环境 API Key > — 4 API Key 是 一 个 用 户 名 (access key) 和 一 个 密码 (secret key) 的 
组 合 - 当 执 行 API 调用 时 ， 两 个 都 需要 用 来 进行 认证 。 在 你 复制 保存 下 相关 信息 后 ， 点 击 
Close ° 


CA 


注意 : 一 旦 你 关闭 了 窗口 ， 你 将 无 法 重新 获得 你 的 API Key 的 密码 (secret key) ， 所 以 确 
保 将 其 保存 在 了 足够 安全 的 地 
使 用 环境 API Keys 


当 配 置 了 权限 控制 且 你 没有 登录 ， 如 果 你 试图 打开 API 端点 ， 你 会 被 提示 需要 一 个 环境 API 
Key。 用 户 名 是 access key ， 密 码 是 secret key > 


如 果 你 使 用 curl ， 你 能 通过 指定 -u 参数 ， 按 照 格式 username:password 来 使 用 环境 API 
Key ， 或 者 能 通过 在 你 netre 文件 内 加 入 一 行 。 

编辑 环境 API Keys 

环境 API Key 的 全 部 选项 都 可 以 通过 位 于 Key 列表 右 侧 的 下 拉 菜 单 进 


对 于 任何 Active 的 key， 你 能 Deactivate 这 个 key， 那 将 阻止 这 些 证 书 的 使 用 。Key 将 会 标 
记 为 Inactive 状态 。 


对 于 任何 Inactive 的 key， 你 有 两 种 选项 。 你 能 Activate 这 个 key， 这 将 重新 允许 证 书 能 访 
问 API。 或 者 ， 你 能 Delete 这 个 key, 那 将 从 环境 中 移 除 这 些 证 书 。 


你 能 Edit 任何 key， 那 允许 你 修改 这 个 环境 API key 的 名 称 和 描述 。 你 没 法 修改 实际 的 
access key 或 secret key。 如 果 你 想 要 新 的 键 值 对 ， 你 需要 创建 一 个 新 的 。 


镜像 仓库 


-- 在 Rancher 中 ， 您 可 以 把 DockerHub、Quay.io 或 者 任何 私有 镜像 仓库 的 访问 账号 添加 进 
来 ， 来 访问 私有 镜像 。 通 过 有 了 访问 您 的 私有 镜像 库 的 功能 ， 它 是 Rancher 可 以 去 使 用 您 的 
私有 镜像 。 这 样 让 从 一 个 私有 地 址 中 加 载 一 个 镜像 变 得 很 简单 。 在 每 一 个 环境 中 ， 每 一 个 镜 
像 仓库 的 地 址 对 一 个 的 访问 账号 信 只 能 有 一 条 ，Rancher 将 总 是 使 用 最 近 添 加 的 哪 一 个 。 


注意 : 目前 ， 镜 像 仓 库 只 在 Cattle 的 环境 中 被 支持 


添加 镜像 仓库 
点 击 Infrastructure 然后 进入 Registries 页 面 ， 点 击 Add Registry ° 


对 于 所 有 的 镜像 仓库 ， 您 将 e A e-mail address, username, 和 password 等 信息 。 对 
于 一 个 Custom AMAR ， 您 还 将 需要 提供 registry address ° A/G Ac Create. 


您 所 添加 的 访问 账号 信息 的 地 址 已 经 存在 了 ，Rancher 将 会 开始 使 用 这 个 新 添加 的 。 


非 加 窖 镜像 仓库 


为 了 访问 一 个 非 加 密 镜 像 仓库 ， 你 讲 需 要 配置 所 有 主机 的 Docker 后 台 访 问 。 poMAIN 和 
PORT 是 提供 私有 镜像 仓库 服务 主机 的 域名 和 端口 。 
注意 : 任何 石油 重启 Sy Docker 服务 ， 您 都 可 能 会 语调 网 络 代 理 被 卡 在 Starting 状态 
的 问题 。 为 了 临时 解决 这 个 问题 ， 请 重启 主机 。 


# 编辑 配置 文件 "/etc/default/docker" 
$ sudo vi /etc/default/docker 


# 在 文件 结束 处 添加 添加 下 面 这 行 。 如 果 已 经 有 这 行 了 ， 则 确保 把 下 面 的 参数 加 载 最 后 
$ DOCKER_OPTS="$DOCKER_OPTS --insecure-registry=${DOMAIN}:${PORT}" 
# 重启 Docker 服务 


$ sudo service docker restart 


自 签名 证 书 


为 了 与 私有 镜像 仓库 使 用 一 个 自 签 发 证 书 。 pomar 和 PORT 是 私有 镜像 仓库 服务 所 在 的 地 
dE o 


openssl s_client -showcerts -connect ${DOMAIN}:${PORT} </dev/null 2>/dev/null|openss 
1 x509 -outform PEM >ca.crt 


A 


$ sudo cp ca.crt /etc/docker/certs.d/${DOMAIN}/ca.crt 


e 


cat ca.crt | sudo tee -a /etc/ssl/certs/ca-certificates.crt 


$ sudo service docker restart 


使 用 镜像 仓库 


在 镜像 仓库 被 创建 之 后 ， 你 将 能 在 启动 服务 或 者 容器 的 时 候 使 用 这 些 私有 镜像 仓库 。 镜 像 名 
称 的 语法 是 与 您 在 docker run 命令 中 是 相同 的 。 


[registry-name]/[namespace]/[imagename]: [version] 


默认 情况 下 ， 我 们 假设 您 总 是 从 DockerHub 来 下 拉 镜 像 。 


编辑 镜像 仓库 
在 镜像 仓库 清单 中 的 


All options for a registry are accessible through the dropdown menu on the right hand side of 
the listed registry. 


For any Active registry you can Deactivate the registry which would prohibit access to the 
registry. No new containers can be launched with any images in that registry. 


For any Deactivated registry, you have two options. You can Activate the registry, which will 
allow containers to access images from those registries. Any members of your environment 
will be able to activate your credential without needing to re-input the password. If you don't 
want anyone using your credential, you should Delete the registry, which will remove the 
credentials from the environment. 


You can Edit any registry, which allows you to change the credentials to the registry 
address. You will not be able to change the registry address. The password is not saved in 
the "Edit" page, so you will need to re-input it in order to save any changes. 


Note: If a registry is invalid (i.e. inactive, removed, or overridden due to a newer 
credential), any service or container using a private registry image will continue to run. 
Since the image has already been pulled onto the host, there will be no restrictions on 
usage of the image regardless of registry permissions. Therefore, any scaling up of 
services or additional containers using the image will be able to run. Rancher does not 
check if the credentials are still valid when running containers as we assume that 
you've already given the host permissions to access the image. 


使 用 Docker 原生 命令 行 


Rancher 与 Docker 原 生命 令 行 的 集成 ， 使 它 能 够 轻易 地 与 其 他 DevOps、Docker 工 具 结合 使 
用 。 Ten 面 来 说 ， 在 Rancher 的 外 部 去 司 动 ， 停 止 或 者 销毁 容器 ，Rancher 也 将 会 检 
测 到 这 些 容器 的 变化 ， 并 将 其 更 新 到 对 应 的 状态 


Docker 事件 监控 


Rancher 通 过 监听 Docker events 来 更 新 所 有 主机 的 容器 状态 。 当 在 Rancher 平 台 之 外 启动 、 
停止 或 者 销毁 容器 (比如 说 ， 直 接 在 主机 上 执行 docker stop sad_einstein ) ，Rancher 将 会 
检测 到 这 些 容器 的 所 发 生 的 变化 并 将 其 更 新 到 相应 的 状态 。 


ER: 当前 的 一 个 限制 是 : Rancher 会 等 待 容器 已 经 启动 了 (不 是 创建 ) 才 会 将 其 导 
到 Rancher， 执 行 docker create ubuntu 会 导致 这 个 容器 在 Rancher UI 上 消失 ， 但 是 执 
行 docker start ubuntu 或 者 docker run ubuntu 则 不 会 。 


Rancher 通 过 docker events 命令 去 监控 一 个 主机 上 容器 的 变化 ， 你 也 可 以 试 试 使 用 这 个 命令 
去 观察 Docker 的 事件 流 。 


将 已 启动 的 容器 加 入 到 Rancher 中 
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在 跨 主 机 的 网 络 中 。 在 创建 容器 的 时 候 添加 一 个 值 


为 true 的 io.rancher.container .network 标签 来 启用 这 个 特性 


$ docker run -1 io.rancher.container.network=true -itd ubuntu bash 
如 需 了 解 更 多 关于 Rancher 管 理 网 络 和 跨 主机 网 络 ， 请 阅读 Rancher 基 本 概念 . 


导入 已 存在 的 容器 


Rancher 还 支持 直接 导入 主机 上 已 经 存在 的 容器 。 你 可 以 参考 添加 自己 的 主机 添加 一 个 自己 的 
主机 ， 添 加 之 后 会 发 现 主 机 上 所 有 的 容器 都 会 被 检测 到 并 导入 Rancher 中 。 


定期 同步 状态 


余 了 实时 监听 Docker 事 件 外 ，Rancher 还 定期 的 去 同步 主机 的 状态 。Rancher 每 隔 5 秒 钟 会 去 
ee 容器 信息 ， 以 确保 平台 上 所 展示 的 容器 状态 和 实际 的 主机 上 的 状态 相符 。 防 
止 由 于 网 络 中 a 务 器 重启 导致 Rancher 没 接受 到 Docker 事 件 。 使 用 这 种 方式 去 同步 状 
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i a. 器 状态 将 会 和 主机 上 的 容器 状态 保持 一 致 。 比 如 说 ，Rancher 觉 得 一 个 容 
en 运行 中 ， 但 它 在 主机 上 实际 上 是 被 停止 了 ，Rancher 将 会 把 该 容器 的 状态 更 新 成 停止 状 
Ss) MAREA ZE o 这 个 容器 


使 用 Rancher-Compose 


Jitao Hou 正在 翻译 首 稿 ， 欢 迎 之 后 Review 


Rancher-compose 工具 就 像 一 个 多 主机 版 本 的 docker-compose . 它 直 接 操作 Rancher 图 形 界 面 
中 的 应 用 栈 (stack) roo (environment) ， 并 且 包 含 很 多 主机 (hosts) . 
由 rancher-compose 启动 的 容器 将 会 被 部 署 在 所 属 环境 内 的 任意 满 ~ 度 规则 (scheduling 
rules) 的 主机 节点 上 . ee 规则 ， 服 务 中 的 容器 将 会 在 已 启动 容器 数目 较 
少 的 节点 上 来 启动 。 因 为 使 用 相同 的 API 调 用 ， ee 户 界面 中 局 动 服 
务 的 效果 一 样 ， 服 务 中 的 容器 将 会 被 拉 起 。 


Rancher-compose 工具 就 像 大 家 熟知 的 docker-compose 一 样 ， 支持 任意 的 docker- 
compose.yml 文件 . 另外 它 还 支持 rancher -compose.yml 文件 ， 该 SHARE f docker- 
compose.yml 的 定义 ， 包 含 了 很 多 只 有 在 Rancher 环 境 才 被 支持 的 属性 ， 如 ， 服 务 中 容器 
动 数 量 等 。 


如 需 深入 掌握 本 章 关 于 rancher- compose 的 知识 ， 用 户 需 要 对 docker-compose 有 基本 的 了 解 。 
请 在 开始 使 用 rancher-compose 之 前 ， 通 读 docker-compose documentation + 


该 命令 的 二 进 制 文件 可 以 直接 在 用 户 界 面 (UI) 中 下 载 ， 下 载 的 链接 位 于 UI 的 右 下 角 ， 其 中 
包含 支持 Windows, Mac 和 Linux 的 命令 行文 件 . 


你 也 可 以 参考 releases page for rancher-compose 来 直接 下 载 该 工具 。 


在 Rancher 服 务 器 中 设置 Rancher-Compose 


为 了 使 得 rancher-compose 能 够 在 Rancher 的 实例 中 局 ks 你 需要 设置 一 些 环 境 变量 ， 或 
者 在 rancher-compose 命令 行 中 以 选项 的 方式 传递 这 些 变 这 些 所 需要 的 环境 变量 

是 RANCHER_URL , RANCHER_ACCESS_KEY ,和 RANCHER_SECRET_KEY . Access key 和 Secret key 届 于 
API key. 


bash 

# Set the url that Rancher is on 

$ export RANCHER_URL=http://server_ip:8080/ 

# Set the access key, i.e. username 

$ export RANCHER_ACCESS_KEY=<username_of_key> 
# Set the secret key, i.e. password 

$ export RANCHER_SECRET_KEY=<password_of_key> 


如 果 你 选择 不 设置 这 些 环境 变量 ， 你 将 会 需要 在 rancher-compose 命令 行 中 以 选项 的 方式 传递 
这 些 变量 。 
bash 


$ rancher-compose --url http://server_ip:8080 --access-key <username_of_key> --secret- 
key <password_of_key> up 


现在 , 你 可 以 利用 rancher-compose 搭配 任意 的 docker-compose.yml 文件 来 启动 服务 . 该 服务 
将 会 在 API Key 所 在 的 environment 中 的 相关 Rancher 实例 里 自动 被 启动 。 


如 需 了 解 关 于 命令 和 选项 的 更 多 信息 ， 请 参考 rancher-compose command 文档 . 
命令 举例 


bash 

# Creating and starting a service without environment variables and picking a stack 

$ rancher-compose --url URL_of_Rancher --access-key username_of_API_key --secret-key p 
assword_of_API_key -p stack1 up 

# To change the scale of an existing service 

$ rancher-compose -p stack1 scale web=3 


2 
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oo rancher -compose 不 会 删 除 服 务 了 容器 do x 意味 着 如 果 你 在 一 行内 有 两 

个 up 命令 ， 第 二 个 up 将 不 起 作用 。 这 是 因为 第 一 个 up 指令 将 会 创建 每 个 对 象 ， 并 且 让 它 运 
行 。 ee -d 选项 给 up 指令 ， rancher -compose 也 不 会 删除 你 的 服务 。 你 必须 使 
用 rm 来 删除 一 个 服务 


Build 


有 两 种 方式 来 支持 docker build。 第 一 种 是 设置 build: 到 一 个 与 Docker Remote API 中 的 远 
程 参数 相 兼容 的 git 地 址 或 HTTP URL。 第 二 种 方法 是 设置 build: 到 一 个 本 地 目录 ，build 的 
上 下 文 将 会 被 上 传 到 S3， 然 后 在 每 个 节点 上 按 指令 构建 。 


为 了 基于 S3 的 build 正 常 工 作 ， 你 必须 设置 AWS credentials。 我 们 提供 了 如 何在 rancher- 
compose 使 用 S3 的 详细 样 例 


Sidekicks 


使 用 服务 时 ， 你 可 能 需要 你 所 定义 的 服务 使 用 volumes_from 和 net 来 指向 另外 一 个 服务 .为 
了 达到 这 个 目的 ， 你 需要 设置 sidekick 关 系 。 Sidekick 关 系 使 得 Rancher 能 够 像 一 个 单元 一 样 
来 伸缩 和 调度 一 组 服务 。 举 例 : B 是 A 的 sidekick, 这 两 个 服务 将 会 被 始终 成 对 部 署 ， 服 务 中 的 
容器 数量 也 将 始终 是 一 样 的 。 


另外 你 需要 定义 sidekick 的 情形 是 ， 你 需要 确保 多 个 服务 始终 部 署 在 同一 个 主机 节点 上 。 


为 了 设置 sidekick 关 系 , 你 需要 为 其 中 一 个 服务 加 上 标签 (label) 。 标 签 的 关键 字 是 
io.rancher.sidekicks ， 其 赋值 是 一 个 服务 或 多 个 服务 名 称 。 如 果 你 需要 添加 多 个 服务 作为 


sidekick， 这 些 服 务 名 称 需 要 用 去 号 隔 开 。 举 例 : io.rancher.sidekicks: sidekick1, sidekick2, 
sidekick3 


为 一 个 服务 定义 了 sidekick 之 后 ， 你 将 不 需要 在 rancher-compose 里 设置 link， 因 为 这 些 这 些 在 
同一 环境 的 服务 将 会 自动 被 DNS 解析 到 。 


主 服务 


包含 sidekick 的 服务 被 称 之 为 主 服务 ,其 sidekick 将 被 认为 是 从 服务 。 主 服务 的 尺寸 (容器 多 
Y) 将 会 被 应 用 于 所 有 在 sidekick 的 从 服务 。 如 果 你 所 有 服务 的 尺寸 不 一 致 ， 主 服务 的 尺寸 将 
会 被 用 在 所 有 服务 上 。 


当 为 定义 了 sidekick 的 服务 配置 负载 均衡 器 时 ， 你 只 能 为 主 服务 设置 目标 服务 。Sidekick 服 务 
不 能 够 被 定义 为 目标 服务 


Rancher-Compose 中 的 Sidekick 举 例 : 


Sample configuration docker-compose.yml 


yaml 
test: 
tty: true 
image: ubuntu:14.04.2 
stdin_open: true 
volumes_from: 
- test-data 
labels: 
io.rancher.sidekicks: test-data 
test-data: 
tty: true 
command: 
- cat 
image: ubuntu:14.04.2 
stdin_open: true 


Sample rancher -compose.yml 


test; 
scale: 2 

test-data: 
scale: 2 


Rancher-Compose Y 47 Sidekick# t] : 多 个 服务 使 用 同一 


A volumes from 


如 果 你 有 多 个 服务 使 用 同一 个 容器 来 做 volumes_from , 你 可 以 为 主 服务 增加 一 个 定义 为 
sidekick 的 从 服务 ， 来 使 用 同一 个 数据 容器 。 因 为 只 有 一 个 容器 能 够 被 作为 负载 均衡 的 目标 ， 
所 以 请 确保 选择 一 个 正确 的 服务 作为 主 服务 ( 即 定义 了 sidekick 标 签 的 服务 ) 。 


yaml 
test-data: 
tty: true 
command: 
- cat 
image: ubuntu:14.04.2 
stdin_open: true 
testi: 
tty: true 
image: ubuntu:14.04.2 
stdin_open: true 
labels: 
io.rancher.sidekicks: test-data, test2 
volumes_from: 
- test-data 
test2: 
tty: true 
image: ubuntu:14.04.2 
stdin_open: true 
volumes_from: 
- test-data 


为 服务 添加 链接 (link) 


在 Rancher 中 ， 同 一 个 环境 里 的 所 有 服务 都 是 可 以 被 DNS 解析 到 的 ， 所 以 并 不 需要 为 服务 显示 
地 添加 链接 (link) ， 除 非 你 需要 使 用 一 个 指定 的 别名 来 做 DNS 解析 。 


Note: 目前 我 们 不 支持 将 sidekick 链 接 到 主 服务 或 者 主 服务 连接 到 sidekick。 更 多 信息 ， 
请 参考 Rancher 内 置 DNS 的 工作 原理 . 


属于 同一 个 应 用 栈 的 服务 ， 任 何 服务 可 以 按照 自己 原 有 的 服务 名 称 被 DNS 解析 到 , 当然 ， 你 可 
以 定义 链接 ， 如 果 你 希望 为 某 一 个 服务 定义 别名 的 话 。 


docker -compose.yml 的 一 个 例子 


wordpress: 


image: wordpress 
links: 
- db:mysql 

db: 


image: mysql 


在 这 个 例子 中 ，dp 将 被 解析 为 mysql . 如 果 没 有 定义 链接 (link), db 将 只 能 按 db 解析 . 
在 其 它 应 用 栈 中 的 服务 ， 服 务 将 会 按照 service name.stack name 的 格式 被 DNS 解析 。 如 果 你 
需要 使 用 一 个 指定 的 别名 做 DNS 解析 ， 你 需要 在 docker -compose.yml 中 定义 


external_links ° 


docker -compose.yml 的 一 个 例子 


wordpress: 
image: wordpress 
external_links: 
- alldbs/db1:mysql 


在 这 个 例子 中 ，alldbs 应 用 栈 中 有 一 个 dbl 服务 ，wordpress 将 会 链接 到 它 。 在 


wordpress 服务 中 ，db1 将 会 被 解析 为 mysql . 如 果 没 有 定义 external link, db1 将 
按 db1.alldbs 解析 . 


备注 : 跨 应 用 栈 的 服务 发 现 只 限于 同一 个 环境 之 内 (by design)， 不 支持 跨 环境 的 服务 发 
现 。 


使 用 Rancher Compose 


A 


u 


令 和 选项 
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The rancher-compose tool works just like the popular docker-compose and supports any 


docker-compose.yml file. There is also a rancher-compose.yml which extends and overwrites 


docker-compose.yml. The rancher-compose yaml file are attributes only supported in 


Rancher, for example, scale of a service. 


Rancher-Compose Commands 


rancher -compose Supports any command that docker-compose supports. 


Name Description 
create Create all services but do not start 
up Bring all services up 
start Start services 
logs Get service logs 
restart Restart services 


stop , down 


Stop services 


scale Scale services 

rm Delete services 

pull Pulls images for services 

upgrade Perform rolling upgrade between services 

help, h Shows a list of commands or help for one command 


Rancher-Compose Options 


Whenever you use the rancher-compose command, there are different options that you can 
use. 


Name Description 


--verbose , --debug 
--file , -f "docker- Specify an alternate compose file (default: docker- 
compose.yml" compose.yml) [SCOMPOSE_FILE] 
--project-name , -p Specify an alternate project name (default: directory name) 
--url Specify the Rancher API endpoint URL [$RANCHER_URL] 


Specify Rancher API access key 
[SRANCHER_ACCESS KEY] 


--access-key 


Specify Rancher API secret key 
[SRANCHER_SECRET_KEY] 


--secret-key 


Specify an alternate Rancher compose file (default: 


sd» Dei rancher-compose.yml) 
--env-file , -e Specify a file from which to read environment variables 
--help , -h show help 
--version , -v print the version 
Examples 


arting a service without environment variables and defining a stack name 
$ rancher-compose --url URL_of_Rancher --access-key username_of_API_key --secret-key p 
assword_of_API_key -p stack1 up 


To change the scale of an existing service 


$ rancher-compose -p stack1 scale web=3 


Note: If you don't pass in -p STACK_NAME , the stack name will be the directory that you 


are running the rancher-compose command in. 


Command Options 


Up Command 


Name Description 


Before doing the upgrade do an image pull on all hosts that 


wa, Kal have the image already 
-d Do not block and log 
--upgrade , -u, : : 
DP a Upgrade if service has changed 


--force-upgrade 


a Upgrade regardless if service has changed 


Confirm that the upgrade was success and delete old 
--confirm-upgrade , -c 


containers 
--rollback , -r Rollback to the previous deployed version 
= batch size "2" Number of containers to upgrade at once 
--interval "1000" Update interval in milliseconds 


When you run the up command with rancher-compose , after all the tasks are complete, the 
process continues to run. If you want the process to exit after completion, you'll need to add 
inthe -d option, which is to not block and log. 


$ rancher-compose up 
e the -d for rancher-compo: 


$ rancher-compose up -d 


Read more about upgrading using rancher-compose. 


Start Command 


Name Description 


-d Do not block and log 


If you want the start process to exit after completion, you'll need to add in the -a option, 
which is to not block and log. 


Logs Command 


Name Description 


--lines "100" number of lines to tail 


Restart Command 


Name Description 
--batch-size "1" Number of containers to retart at once 
--interval "0" Restart interval in milliseconds 


By default, restarting services will restart the containers individually and immediately 
sequentially. You can set the batch size and interval of the restart policy. 


Stop/Down 8 Scale Command 


Name Description 


--timeout , -t "10" Specify a shutdown timeout in seconds. 


Rm Command 


Name Description 


--force , -f Allow deletion of all services 


Pull Command 


Name Description 


--cached , -c Only update hosts that have the image cached, don't pull new 


$ rancher-compose pull 


$ rancher-compose pull --cached 


Note: Unlike docker-compose pull , you will not be specifying which service to pull. 
Rancher-compose looks at all services in the docker-compose.yml and pulls images for 
all services found in the file. 


Upgrade Command 


Rancher supports upgrades to services using rancher-compose . Please read more about 
when and how to upgrade your services. 


Name Description 
ee Number of containers to upgrade at once 
--scale "-1" Final number of running containers 
ae Update interval in milliseconds 
--update-links Update inbound links on target service 
--wait , -w Wait for upgrade to complete 

Before doing the upgrade do an image pull on all hosts that have 

a EE the image already 
ve, ee Remove the original service definition once upgraded, implies -- 


wait 


# Upgrade service1 to service2 
# servicel and service2 to be defined in the docker-compose.yml 


$ rancher-compose upgrade service1 service2 


# Upgrade to a different scale 


$ rancher-compose upgrade servicel service2 --scale 5 


# Removes servicei from Rancher 


$ rancher-compose upgrade servicel service2 --cleanup 


Compose Compatibility 


rancher-compose Strives to be completely compatible with Docker Compose. Since rancher- 
compose is largely focused on running production workloads some behaviors between 
Docker Compose and Rancher Compose are different. 


We support anything that can be created in a standard docker-compose.yml file. There are a 
couple of differences in the behavior of rancher-compose that are documented below. 


Deleting Services/Container 


rancher-compose Will not delete things by default. This means that if you do two up 
commands in a row, the second up will do nothing. This is because the first up will create 
everything and leave it running. Even if you do not pass -da to up, rancher-compose Will 
not delete your services. To delete a service you must use rm. 


Rancher 服务 
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Rancher implements a distributed health monitoring system by running an HAProxy instance 
on every host for the sole purpose of providing health checks to containers. When health 
checks are enabled either on an individual container or a service, each container is then 
monitored by up to three HAProxy instances running on different hosts. The container is 
considered healthy if at least one HAProxy instance reports a "passed" health check and it is 
considered unhealthy when all HAProxy instances report a "unhealthy" health check. 


Rancher's approach handles network partitions and is more efficient than client-based health 
checks. By using HAProxy to perform health checks, Rancher enables users to specify the 
same health check policy for DNS service and for load balancers. 


Note: Health checks will only work for services that are using the managed network. If 
you select any other network choice, it will not be monitored. 


To enable health checks for services, we add the health check in the rancher-compose.yml 
file. 


wordpress: 

scale: 1 

health_check: 
port: 80 
# Interval is measured in milliseconds 
interval: 2000 
unhealthy_threshold: 3 
# For TCP, request_line needs to be 
# TCP Example: 
# request_line: 
request_line: GET /healthcheck HTTP/1.0 
healthy_threshold: 2 
# Response timeout is measured in milliseconds 


Bar 
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response_timeout: 2000 


More details about Health Checks can be read in the concept section. 


Note: If a host is down in Rancher (i.e. in reconnecting Or inactive state), you will 
need to implement a health check in order for Rancher to launch the containers on your 


service on to a different host. 


Custom Rancher Services 


Custom Rancher services are configured by using a special image name in the compose 
template. The image name is how rancher-compose knows to set up a Rancher service 
versus a normal service. 


Service Image Name 
Load Balancer rancher/load-balancer-service 
External Service rancher/external-service 
Alias/DNS Service rancher/dns-service 


Load Balancer 


A load balancer can be scheduled like any other service. Read more about scheduling 
services and load balancers using rancher-compose . 


Rancher supports L4 load balancing by adding ports and linking target services. Any traffic 
directed to any of source port(s) will be sent to the private port(s) of the linked service(s). 


Note: Port 42 cannot be used as a source port for load balancers because it's 
internally used for health checks. 


When working with services that contains sidekicks, you need to link the primary service, 
which is the service that contains the sidekick label. 


Note: Load balancers will only work for services that are using the managed network. If 
you select any other network choice for your target services, it will not work with the 
load balancer. 


Load Balancer Example (L4) 


Sample configuration docker-compose.yml 


1b: 
image: rancher/load-balancer-service 
ports: 





A yn a random public port and direct traffic to private port 80 of the service. 
- 80 
Listen on public port 80 and direct traffic to private port 80 of the 


- 80:80 


TTP 





not TP 
- 9999/tcp 
links: 





Target services in the same stack will be listed as a link 
- web1:web1 
- web2:web2 
external_links: 





ar + carvi e in a diffarant ctark wil | ar a ar wa) las 
Target services in a different stack will be listed as a external link 


- differentstack/web3:web3 


Sample rancher-compose.yml 


lb: 

Two load balancer containers 
scale: 2 
load_balancer_config: 

name: lb config 

web1: 
scale: 1 

web2: 
scale: 1 

web3: 
scale: 1 


Advanced Load Balancing (L7) 


We also support L7 load balancing with advanced routing options, which include using host 
headers, host paths and specific target ports. We go into more detail on advanced routing 
options for load balancers in our Ul section, but anything that we can create in Rancher can 
be created using rancher-compose 


Advanced routing options use labels inthe docker-compose.yml file. Here's the basic 
syntax for applying the label. You would only use this label if you were going to do some 
advanced routing rules. Advanced routing rules are optional and all of the fields are optional 
as well. This syntax shows if you were to use all the options. 


Label Key Label Value 


io.rancher.loadbalancer.target. <REQUEST_HOST>: <SOURCE_PORT>/<REQUEST_PATH>= 
<SERVICE_NAME> <TARGET_PORT> 


Note: If you use a source port with the advanced routing options, the source port must 


also be listed in ports section of the docker-compose.yml 


Linking Services in a Different Stack 


In the label for target services, <sERVICE NAME> is the name of the service. If your service is 
in another stack, the <SERVICE_NAME> will need to include stack name using the following 
format <STACK_NAME>/<SERVICE_NAME> . The link to the target service of other stacks will be 


under external_links . 


Syntax of the Combination of all Optional Fields 


Since the fields are optional, we support all combinations of the fields. Here is the syntax for 
all combinations using request host, source port, path and target port. 


Request Source Target 


Host Port Path Port Label Value 
example.com 80 /path 81 example .com:80/path=81 
example.com 80 /path/a example .com:80/path/a 
example.com 80 81 example .com: 80=81 
example.com 80 example.com:80 
example.com /path/b/c 81 example.com/path/b/c=81 
example.com /path example.com/path 
example.com 81 example.com=81 
example.com example.com 

80 /path 81 80/path=81 

80 /path 80/path 

80 81 80=81 
/path 81 /path=81 
/path /path 


81 '81' *See Note 


Note: It is assumed that if you have only a port in the label, then the port is for the 
target port of the service. When using only a target port, it must be surrounded by 
single quotes. 


Wildcards 


Rancher supports wildcards when adding host based routing. The following wildcard syntax 
is supported. 


*.domain.com -> hdr_end(host) -i .domain.com 
domain.com.* -> hdr_beg(host) -i domain.com. 


Multiple Routing Rules for the Same Service 


In rancher-compose , you can configure multiple hostname routing rules to the same service 
by separating each rule with a comma. See the example for service web2 . 


Priority 
When there are multiple hostname routing rules, the order of priority is as follows: 


Hostname and URL 

Hostname only 

URL 

Default (no hostname, no URL) 


Pon 


Load Balancer Example (L7) 


Sample configuration docker-compose.yml 


Rancher 服务 


lb: 


image: rancher/load-balancer-service 


ports: 


# Listen on public port 80 and direct traffic to private port 80 of the service 


- 80:80 


# Listen on public port 82 and by default forward traffic to private port 81 using H 


TTP 
SEBAB T 


# Listen on public port 9999 using TCP and not HTTP 


9999/tcp 
links: 


# Target services in the same stack will be listed as a link 


- web1:webla 
- web2:web2a 


external_links: 
# Target services in a different stack will be listed as an external link 
- differentstack/web3:web3a 


labels: 
# Put load 


io.rancher. 


# Requests 


io.rancher. 


# Requests 


# and http: 
io.rancher. 


bar=8001 
# Requests 
# of 82:81 


io.rancher. 


balancer containers on hosts with label lb=true 
scheduler .affinity:host_label: lb=true 
to http://app.example.com/foo:80 should be routed to web1 over port 8000 


loadbalancer.target.web1: app.example.com: 80/f00=8000 

to http://app.example.com/foo should be routed to web2 over port 8000 
//app.example.com/foo/bar over port 8001 

loadbalancer.target.web2: app.example.com/foo=8000, app.example.com/foo/ 


routed to web3 go to port 8000, overriding the default configuration 


loadbalancer.target.differentstack/web3: 82=8000 


天 二 一 mm 


Sample rancher-compose.yml 


lb: 


# Two load balancer containers 


scale: 2 


load_balancer_config: 


name: lb config 


web1: 
scale: 1 

web2: 
scale: 1 

web3: 
scale: 1 


Internal Load Balancer 
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To set an internal load balancer, the listening ports are listed under expose instead of 


ports . 


Sample configuration docker-compose.yml 


lb: 
image: rancher/load-balancer-service 
# Instead of using ports, we use expose to define that it will be private ports 
expose: 
# Listen on private port 80 and direct traffic to private port 80 of the service 
- 80:80 
# Listen on private port 82 and by default forward traffic to private port 81 using 
Hine 
- 82:81 
links: 
# Any service that is a target will be listed as a link 
- web1:webi 


Sample rancher -compose. yml 


lb: 
# Two load balancer containers 
scale: 2 
load_balancer_config: 
name: lb config 
web1: 
scale: 1 


Custom haproxy.cfg 


For advanced users, you can specify global and defaults configuration to the load 
balancer in the rancher-compose.yml . Please refer to the HAProxy documentation for details 
on the available options you can add. 


Sam ple rancher-compose.yml 


1b: 
scale: 1 
load_balancer_config: 
haproxy_config: 
defaults: <DEFAULTS_INPUTS> 
global: <GLOBAL_INPUTS> 
health_check: 
port: 42 
interval: 2000 
unhealthy_threshold: 3 
healthy_threshold: 2 
response_timeout: 2000 


External Service 


With external services, you can set either external IP(s) OR a domain name. The 
rancher/external-service is not an actual image, but is required for the docker- 
compose.yml. There are no containers created for external services. 


Sample configuration docker-compose.yml 


db: 
image: rancher/external-service 


redis: 
image: redis 


Sample rancher-compose.yml using external IPs 


db: 
external_ips: 
= ala 
E 22,2 


redis: 
image: redis 
external_ips: 
al 
SEAN ZZ 


Sample rancher-compose.yml using hostname 


db: 
hostname: example.com 


Service Alias/Internal DNS service 


A service alias creates a pointer to service(s). In the example below, web[.stack- 
name.rancher.internal] will resolve to the IPs of the containers of web1 and web2 . The 

rancher/dns-service is not an actual image, but is required for the docker-compose.yml. 
There are no containers created for alias services. 


Sample configuration docker-compose.yml 


web: 
image: rancher/dns-service 
links: 
- web1 
- web2 


web1: 
image: nginx 


web2: 
image: nginx 
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When creating services using rancher-compose , you can direct the host(s) of where the 
containers should be launched based on scheduling rules. This scheduling ability is 
available in the Ul and also support in rancher-compose . Rancher determines how to 
schedule a service's containers based on the labels defined in the docker-compose.yml 
file. 


Labels used in Docker-Compose 


All of the labels in this section would be used in the docker-compose.ym1 file. Rancher 
defines the scheduling rules with 3 main components: conditions, fields and values. 
Conditions determine how strictly Rancher follows the rules. Fields are which items that are 
going to be compared against. Values are what you've defined on the fields. We'll talk 
broadly about these components before going into some examples. 


Scheduling Conditions 


When we write our scheduling rules, we have conditions for each rule, which dictates how 
Rancher uses the rule. An affinity condition is when we are trying to find a field that matches 
our value. An anti-affinity condition is when we are trying to find a field that does not match 
our value. 


To differentiate between affinity and anti-affinity, we add _ne to the label name to indicate 
that the label is not matching the field and values. 


There are also hard and soft conditions of a rule. 


A hard condition is the equivalent of saying must or must not. Rancher will only use hosts 
that match or do not match the field and value. If Rancher cannot find a host that meets all of 
the rules with these conditions, your service could get stuck in an Activating state. The 
service will be continually trying to find a host for the containers. To fix this state, you can 
either edit the scale value of the service or add/edit another host that would satisfy all of 
these rules. 


A soft condition is the equivalent of saying should or should not. Rancher will attempt to 
use hosts that match the field and value. In the case of when there is no host that matches 
all the rules, Rancher will remove one by one the soft constraints (should/should not rules) 
until a host satisfies the remaining constraints. 


To differentiate between the must and should conditions, we add _soft to our label name 
to indicate that the label is should try to match the field and values. 


Fields 


Rancher has the ability to compare values against host labels, container labels, container 
name, or service name. The label prefix is what Rancher uses to define which field will be 


evaluated. 
Field Label Prefix 
Host Label io.rancher.scheduler.affinity:host_label 
Container Label/Service Name io.rancher.scheduler.affinity:container_label 
Container Name io.rancher.scheduler .affinity: container 


Notice how there is not a specific prefix for service name. When Rancher creates a service, 
system labels are added to all containers of the service to indicate the stack and service 
name. 


To create the key of our label, we start with a field prefix (e.g. 
io.rancher.scheduler.affinity:host_label ) and based on the condition that we are looking 

for, we append the type of condition we want. For example, if we want the containers to be 

launched on a host that must not equal (i.e. _ne ) to a host label value, the label key would 


be io.rancher.scheduler.affinity:host_label_ne . 


Values 


You use the values to define what you want the field to be checked against. If you have a 
couple of values that you want to compare against for the same condition and field, you'll 
need to use only one label for the name of the label. For the value of the label, you'll need to 
use a comma separated list. If there are multiple labels with the same key (e.g. 

io.rancher.scheduler .affinity:host_label_ne ), Rancher will overwrite any previous value 
with the last value that is used with the label key. 


labels: 
io.rancher.scheduler.affinity:host_label: key1=value1, key2=value2 
Global Service 


Making a service into a global service is the equivalent of selecting Always run one 
instance of this container on every host in the UI. This means that a container will be 
started on any host in the [environment]/rancher/configuration/environments/). If a new host 


is added to the environment, and the host fulfills the global service's host requirements, the 
service will automatically be started. 


Currently, we only support global services with host labels fields that are using the hard 
condition. This means that only labels that are related to host_labels will be adhered to 
when scheduling and it must or must not equal the values. Any other label types will be 
ignored. 


Example docker-compose.yml : 


wordpress: 
labels: 


io.rancher.scheduler.global: 'true' 


io.rancher.scheduler .affinity:host_label: key1=value1 
io.rancher.scheduler.affinity:host_label_ne: key2=value2 
image: wordpress 
links: 
- db: mysql 
stdin_open: true 


Finding Hosts with Host Labels 


When adding hosts to Rancher, you can add host labels. When scheduling a service, you 
can leverage these labels to create rules to pick the hosts you want your service to be 
deployed on. 


Examples for each condition type: 


labels: 
io.rancher.scheduler.affinity:host_label: keyl=valuel 
io.rancher.scheduler.affinity:host_label_ne: key2=value2 


io.rancher.scheduler.affinity:host_label_soft: key3=value3 


io.rancher.scheduler.affinity:host_label_soft_ne: key4=value4 


Automatically Applied Host Labels 


Rancher automatically creates host labels related to linux kernel version and Docker Engine 
version of the host. 


Key Value Description 


Version of the Linux 
kernel running on 
the host 


io.rancher.host.linux_kernel_version Linux Kernel Version 
on Host (e.g, 3.19 ) 
Docker Engine 
io.rancher.host.docker_version Version on the host 
(e.g. 1.10.3 ) 


Docker Engine 
Version on the host 


labels: 

# Host MUST be running Docker version 1.10.3 
io.rancher.scheduler.affinity:host_label: io.rancher.host.docker_version=1.10.3 
# Host MUST not be running Docker version 1.6 
io.rancher.scheduler.affinity:host_label_ne: io.rancher.host.docker_version=1.6 


Note: Rancher does not support the concept of scheduling containers on a host that 
has >= a specific version. You can create specific whitelists and blacklists by using the 
host scheduling rules to determine if a specific version of Docker Engine is required for 
your services. 


Finding Hosts with Container Labels 


When adding containers or services to Rancher, you can add container labels. These labels 
can be used for the field that you want a rule to compare against. Reminder: This cannot be 
used if you set global service to true. 


Note: lf there are multiple values for container labels, Rancher will look at all labels on 
all containers on the host to check the container labels. The multiple values do not need 
to be on the same container on a host. 


Examples for each condition type: 


labels: 
# Host MUST have a container with the label `key1=value1` 
io.rancher.scheduler.affinity:container_label: key1=valuel 
# Host MUST NOT have a container with the label "key2=value2' 
io.rancher.scheduler .affinity:container_label_ne: key2=value2 
# Host SHOULD have a container with the label ~key3=value3~ 
io.rancher.scheduler.affinity:container_label_soft: key3=value3 
# Host SHOULD NOT have a container with the label "key4=value4 
io.rancher.scheduler .affinity:container_label_soft_ne: key4=value4 


Service Name 


When rancher-compose starts containers for a service, it also automatically creates several 
container labels. Since checking for a specific container label is looking for a key=value , we 
can use these system labels as the key of our rules. Here are the system labels created on 
the containers when Rancher starts a service: 


Label Value 
io.rancher.stack.name $${stack_name} 
io.rancher.stack_service.name $${stack_name}/$${service_name} 


Note: When using the io.rancher.stack_service.name , the value must be in the format 


Of stack name/service name . 


The macros $${stack_name} and $${service_name} Can also be used in the docker- 
compose.yml file in any other label and will be evaluated when the service is started. 


Please note that in versions prior to Rancher v0.41.0 and Rancher-compose v0.4.1, the 
values had a single $ , but with the addition of environment interpolation, the values require 
a double ss . 


Example of Service Name: 


labels: 


earvire nama 
Ce alle 


Host MUST have a container from j 


io.rancher.scheduler.affinity:container_label: io.rancher.stack_service.name=stackna 


me/servicename 


Finding Hosts with Container Names 


When adding containers to Rancher, you give each container a name. You can use this 
name as a field that you want a rule to compare against. Reminder: This cannot be used if 
you set global service to true. 


labels: 
seco ee een 
ete eee on na merits value2 
nern eher Schedi ler 0 es 


io.rancher.scheduler.affinity:container_soft_ne: value4 


Examples 


Example 1: 


A typical scheduling policy may be to try to spread the containers of a service across the 
different available hosts. One way to achieve this is to use an anti-affinity rule to itself: 


labels: 
io.rancher.scheduler.affinity:container_label_ne: io.rancher.stack_service.name=$${s 
tack_name}/$${service_name} 


Since this is a hard anti-affinity rule, we may run into problems if the scale is larger than the 
number of hosts available. In this case, we might want to use a soft anti-affinity rule so that 
the scheduler is still allowed to deploy a container to a host that already has that container 

running. Basically, this is a soft rule so it can be ignored if no better alternative exists. 


labels: 
io.rancher.scheduler.affinity:container_label_soft_ne: io.rancher.stack_service.name 
=$${stack_name}/$${service_name} 


Example 2: 


Another example may be to deploy all the containers on the same host regardless of which 
host that may be. In this case, a soft affinity to itself can be used. 


labels: 
io.rancher.scheduler.affinity:container_label_soft: io.rancher.stack_service.name=$$ 
{stack_name}/$${service_name} 


If a hard affinity rule to itself was chosen instead, the deployment of the first container would 
fail since there would be no host that currently has that service running. 


Table of Scheduling Labels 


Label Value 
io.rancher.scheduler.global true 
io.rancher.scheduler.affinity:host_label key1=value1,key2=value2, etc... 
io.rancher.scheduler.affinity:host_label_soft key1=value1,key2=value2 
io.rancher.scheduler.affinity:host_label_ne key1=value1,key2=value2 
io.rancher.scheduler.affinity:host_label_soft_ne key1=value1,key2=value2 


io.rancher.scheduler.affinity:container_label key1=value1,key2=value2 


io.rancher.scheduler.affinity:container_label_soft key1=value1,key2=value2 


io.rancher.scheduler.affinity:container_label_ne key1=value1,key2=value2 


io.rancher.scheduler.affinity:container_label_soft ne key1=value1,key2=value2 


io.rancher.scheduler.affinity:container container _name1,container_name: 


io.rancher.scheduler.affinity:container_soft container_name1,container_name: 


io.rancher.scheduler.affinity:container_ne container_name1,container_name: 


io.rancher.scheduler.affinity:container_soft_ne container_name1,container_name: 


升级 服务 


环境 插值 


构建 使 用 AWS S3% 1A 


Rancher 图 像 界 面 


rancher 中 的 标签 和 人 调度 


当 通 过 服务 (service)， 或 者 通过 负载 均衡 器 (loadbalancer)， 或 者 通过 容器 页 面 (container 
page) 启 动容 器 的 时 候 ， 我 们 提供 为 容器 创建 标签 的 选项 以 及 提供 调度 容器 到 你 想 要 放置 容器 
的 主机 上 的 能 力 。 在 这 章节 剩 下 的 部 分 ， 我 们 将 使 用 术语 容器 /服务 (container/service), 但 这 些 
标签 也 适用 于 负载 均衡 器 (也 就 是 一 种 特殊 类 型 的 服务 ) 。 


度 规则 为 你 想 a... 的 主机 提供 了 灵活 性 。 在 Rancher 中 ， 我 们 使 用 标签 
规则 。 你 能 为 一 个 容器 创建 你 想 要 的 数量 的 标签 。 有 了 多 种 规则 ， 你 完全 控 
制 哪 种 主机 上 创建 容器 。 你 可 以 请 求 具有 特定 主机 标签 ， 容 器 标签 或 名 字 ， 或 者 特定 服务 的 
容器 在 一 台 主 机 启动 。 这 些 调度 规则 能 帮助 创建 你 容器 托管 关系 的 黑 名 单 和 和 白 名 单 。 


标签 
对 于 服务 /容器 , 标签 可 以 在 Advanced Options -> Labels 中 找到 。 对 于 负载 均衡 器 ， 标 签 可 


以 在 Labels 选 项 卡 中 找到 。 


通过 添加 标签 给 负 器 ， 每 个 负载 均衡 器 容器 都 会 收 到 该 标签 ， 这 标签 是 一 个 键 值 对 。 
Rancher 中 我 们 使 用 这 些 容 器 标签 来 帮助 定义 调度 规则 。 你 能 在 负载 均衡 器 上 创建 你 想 要 的 数 
量 的 标签 。 nn 个 容器 添加 了 系统 相关 标签 。 


调度 选项 


对 于 服务 /容器 ,标签 能 在 Advanced Options -> Scheduling 中 找到 。 对 于 负载 均衡 器 ， 标 签 
能 在 Scheduling 选 项 卡 中 找到 。 


对 于 服务 /容器 , 提供 了 两 个 选项 来 决定 在 哪里 启动 你 的 容器 。 


选项 1: 在 指定 主机 上 运行 所 有 容器 通过 选择 该 选项 运行 所 有 容器 在 指定 的 主机 ， 容 器 /服务 
将 会 在 指定 的 主机 上 启动 。 如 果 你 的 主机 停止 运行 ， 那 么 主机 上 的 容器 也 将 停止 运行 。 如 果 
你 在 容器 页 面 创建 一 个 容器 ， 即 使 存在 端口 冲突 ， 容 器 也 能 被 启动 。 如 果 你 创建 一 个 规模 
(scale) 大 于 1 的 服务 ， 存 在 端口 冲突 ， 你 的 服务 可 能 陷入 未 激活 状态 (inActivating) 直 到 你 编辑 
服务 的 规模 值 。 


选项 2: 自动 选择 匹配 调度 规则 的 主机 通过 选择 该 选项 自动 选择 匹配 调度 规则 的 主机 ， 
灵活 地 选择 你 的 调度 规则 。 任 何 遵守 所 有 规则 的 主机 都 是 容器 能 在 上 面 启 动 的 主机 。 你 能 通 
过 点 击 + 按 钮 来 添加 规则 。 


对 于 负载 均衡 器 Öfrancher/rancher-ui/applications/stacks/adding- balancers/), 因为 端口 冲突 问 
题 只 有 选项 2 是 有 效 的 。 你 只 能 选择 添加 调度 规则 。 点 击 Scheduling 选 项 卡 。 你 能 通过 Add 
Scheudling Rule 按 钮 添加 你 想 要 的 调度 规则 。 


对 于 每 个 规则 ， 你 要 选择 规则 的 条 件 。 有 四 个 不 同 的 条 件 ， 分 别 定义 规则 必须 遵守 的 规则 有 
多 严格 。 字 段 (field) 决 定 由 你 希望 规则 应 用 于 哪些 字段 。 键 和 值 是 那些 你 想 要 检查 的 字段 的 
值 。 如 果 你 启动 一 个 服务 或 者 负载 均衡 器 ，rancher 将 根据 每 台 主 机 上 的 负载 来 传播 容器 的 分 
布 到 合适 的 主机 上 。 决 定 哪些 主机 合适 取决 于 条 件 的 选择 。 


主意 : 对 于 服务 /负载 均衡 器 ， 如 果 你 选择 了 规模 为 总 是 在 每 台 主 机 上 和 运行 这 个 容器 的 一 
个 实例 选项 ， 那 么 只 有 主机 标签 作为 一 个 可 能 的 字段 出 现 。 


e 必须 或 必须 不 : Rancher 只 使 用 匹配 或 者 不 匹配 字段 和 值 的 主机 。 如 果 Rancher 找 不 到 一 
台 主 机 符合 带 有 这 些 条 件 的 所 有 规则 ， 你 的 服务 将 一 直 陷 入 正在 激活 状态 (Activating) > 
服务 将 不 停 为 容器 查找 可 用 的 主机 。 你 能 编辑 服务 的 规模 活着 添加 /编辑 另 一 台 满 足 这 些 
规则 的 主机 。 

© 应 该 或 不 应 该 。Rancher 试 图 使 用 匹配 这 些 字 段 和 值 的 主机 。 在 没有 主机 匹配 所 有 规则 的 
条 件 下 ，Rancher 将 一 个 接 一 个 移 除 软 限制 直到 有 主机 满足 剩 下 的 限制 。 


字段 


e 主机 标签 : 当 为 容器 /服务 选择 主机 时 ，Rancher 将 会 检测 主机 上 的 标签 来 查看 是 否 这 些 
标签 匹配 所 提供 的 键 / 值 对 。 因 为 每 台 主 机 能 有 一 个 或 多 个 标签 ，Rancher 将 把 键 / 值 对 和 
主机 上 所 有 标签 做 对 比 。 当 添加 一 台 主 机 到 Ranche 时 ， 你 就 能 为 主机 添加 标签 。 你 也 能 
通过 主机 下 拉 菜 单 中 的 Edit 选 项 来 编辑 主机 上 的 标签 。 激 活 主机 上 的 标签 列表 可 从 下 拉 菜 

e 带 标 签 的 容器 ; 当选 择 这 个 字段 时 ，Rancher 将 查找 主机 上 存在 已 经 有 标签 匹配 键 值 对 的 
容器 的 主机 。 ,因为 每 个 个 容器 能 有 一 个 或 多 个 标签 ，Rancher 将 把 键 值 对 和 主机 上 的 每 个 容 
器 的 所 有 标签 进行 比较 。 容 器 标签 在 容器 的 Advanced Options -> Lables 选 项 卡 中 。 你 
不 能 在 容器 启动 后 编辑 容器 的 标签 。 为 了 能 创建 拥有 同样 设 定 的 新 容器 ， 你 能 在 容器 户 
动 前 Clone 容 nn 及 增加 新 的 标签 。 正 在 运行 的 容器 的 用 户 标签 列表 看 从 下 拉 菜 
的 键 值 字段 获得 带 名 字 的 服务 : Rancher 将 检测 一 台 主 机 上 是 否 有 指定 服务 的 容器 在 运 
行 。 moro ， 服 务 改 变 了 名 字 或 者 取消 处 于 未 激活 或 者 已 移 除 状态 ， 这 规则 
就 不 再 有 效 。 如 果 你 选择 了 这 个 字段 ， 输 入 的 值 必须 为 栈 名 /服务 名 
(stack_name/service_name) 的 格式 。 正 在 运行 行 的 服务 的 列表 可 以 从 下 拉 菜 单 中 的 值 (value) 
字段 获得 。 

e 带 名 字 的 容器 : Rancher 将 检测 一 台 主 机 上 是 否 指定 的 名 字 的 容器 正 咋 运行 。 如 果 稍 后 的 
时 间 ， 容 器 改变 了 名 字 或 者 处 于 未 激活 /已 移 除 状 态 ， 整 条 规则 变 不 再 有 效 。 运 行 中 的 容 
器 列表 可 以 从 下 拉 菜 单 的 值 (value) 字 段 获得 。 


调度 服务 


120 


服务 /堆栈 


增加 服务 


增加 服务 别名 


增加 负载 均衡 


增加 外 部 服务 


堆栈 选项 


基础 架构 /主机 


从 主机 开始 
从 主机 开始 


在 Rancher 中 ， 我 们 在 UI 上 提供 了 很 简单 的 指导 ， 来 将 那些 直接 支持 的 云 提供 商 所 提供 的 主 
机 添加 进来 ， 同 时 也 提供 了 指导 ， 在 你 的 云 提供 商 不 支持 的 时 候 ,添加 你 拥有 的 主机 。 在 
Infrastructure 中 的 Hosts 页 ， 点 击 Add Host > 


主机 要 求 


o 任何 现代 的 Linux 发 行 版 ， 支 持 Docker 1.10.3。RancherOS, Ubuntu, RHEL/CentOS 7 
经 过 了 更 严格 的 测试 。 

e 1GBRAM 

e 建议 CPU w/ AES-NI 


主机 如 何 工作 ? 


在 rancher 代理 端 在 主机 上 启动 后 ， 主 机 就 连 上 了 Rancher 服务 端 。 注 册 令 牌 ， 就 是 Add 
Host -> Custom 页 面 中 的 长 URL， 用 来 帮助 rancher 代理 端 首次 连 上 服务 端 。 在 连接 中 ， 将 
会 在 Rancher 服务 端 生成 一 个 代理 端 帐号 和 API 密 钥 对 。 密 钥 对 用 来 作为 后 来 的 所 有 通讯 ， 
使 用 如 其 他 类 型 的 帐号 如 环境 API 密 钥 ， 相 同 的 认证 与 授权 逮 辑 。 


设计 如 此 是 因为 代理 端 是 不 可 信 的 ， 因 为 他 运行 在 外 部 的 和 (对 服务 端 ) 有 潜在 敌意 的 硬件 
上 。 代 理 端 帐号 仅 能 在 API 中 访问 他 们 所 需 的 资源 ， 对 事件 的 回复 会 被 检查 确保 事件 确实 发 
送 给 此 代理 端 等 。 由 于 没有 反方 向 的 为 代理 端 来 验证 主机 ， 因 此 你 可 以 设置 TLS 并 且 证 书 将 
会 被 验证 。 


IPSec LARES 环境 独 有 的 。 他 由 服务 端 生成 ， 存 储 在 数据 库 中 ， 并 作为 代理 端 注册 API 
密 钥 对 的 一 部 分 发 送 给 主机 。 连 接 是 在 主机 间 点 对 点 并 AES 加 密 的 ， 其 中 加 密 能 被 大 多 数 的 
现代 CPU 加 速 。 


添加 主机 


尔 第 一 次 添加 主机 时 ， 你 可 能 被 要 求 设置 好 主机 注册 。 设 置 将 检测 何 种 DNS 名 称 或 ip 地 址 及 
端口 用 来 使 你 的 主机 链接 到 Rancher APIl。 默 认 的 情况 下 ， 我 们 选择 管理 服务 端 IP 和 端口 
8080 。 如 果 你 选择 改变 地 址 ， 请 确保 指定 端口 用 来 连接 到 Rancher API > 任何 时 候 你 都 能 够 
更 新 主机 注册 。 在 设置 好 你 的 主机 注册 后 ， 点 击 Save。 


我 们 支持 直接 从 云 提 供 商 添加 主机 ， 或 添加 已 经 被 配置 好 了 的 主机 。 对 于 云 提 供 商 ， 我 们 使 
用 docker-machine 进行 配置 2 并 支持 任何 docker-machine 支持 的 镜像 © 


选择 你 想 添加 的 何 种 主机 类 型 : 


e 添加 自 定义 主机 

e 添加 Amazon EC2 主机 
e 添加 Azure 主机 

e 添加 DigitalOcean 主机 
e 添加 Exoscale 主机 

e 添加 Packet 主机 

e 添加 Rackspace 主机 

o 添加 其 他 驱动 的 主机 


当 一 人 台 主 机 加 入 Rancher > rancher 代理 端 将 会 在 主机 上 启动 。Rancher 将 会 自动 拉 取 
rancher/agent 的 正确 镜像 版 本 标签 并 运行 所 需 的 版 本 。 对 于 每 个 Rancher 服务 端 版 本 ， 代 
理 端 版 本 都 被 明确 标记 。 


主机 标签 


对 于 每 个 主机 ， 你 能 添加 标签 来 协助 组 织 你 的 主机 。 当 启动 rancheragent 容器 时 ， 标 签 作为 
环境 变量 被 添加 。UI| 中 的 主机 标签 将 会 是 key/value 对 并 且 key 都 需要 是 唯一 标识 。 如 果 你 添 
加 了 两 个 相同 的 key 带 有 不 同 value， 我 们 将 使 用 后 输入 的 value 作为 key/value 对 。 


通过 对 主机 添加 标签 ， 你 能 在 调度 服务 /负载 均衡 /服务 中 使 用 标签 ， 创 建 对 你 的 服务 运行 的 主 
机 和 白 名 单 或 黑 名 单 。 


如 果 你 计划 使 用 外 部 DNS 服务 ， 并 需要 编辑 DNS 记录 来 使 用 非 主 机 IP 的 其 他 IP， 你 需要 在 
主机 上 包含 此 标签 io.rancher.host.external_dns_ip=<IP_TO_BE_USED_FOR_EXTERNAL_DNS> ° E 
机 标签 能 在 注册 主机 或 在 主机 添加 进 Rancher 后 添加 ， 但 是 应 该 在 外 部 DNS 服务 开启 前 添 
加 到 主机 。 标 签 的 值 将 会 在 编辑 外 部 DNS 服务 的 规则 时 被 使 用 。 





当 使 用 UI 添加 不 同 云 提 供 商 的 主机 时 ，rancher/agent 命令 会 自动 为 你 执行 并 带 有 通过 UI| 添 加 
的 主机 标签 。 


当 添 加 自 定义 主机 ， 你 能 通过 UI 添加 标签 并 且 它 将 自动 添加 带 有 key/value 对 的 环境 变量 
( CATTLE_HOST_LABELS ) 到 UI 界面 的 命令 中 。 


例子 


# 添加 一 个 主机 标签 到 rancher/agent 命令 中 
$ sudo docker run -e CATTLE_HOST_LABELS='foo=bar' -d --privileged \ 
-v /var/run/docker.sock:/var/run/docker.sock rancher/agent:v0.8.2 \ 
http: //<rancher -server -ip>:8080/v1/projects/la5/scripts/<registrationToken> 
H 添加 多 于 一 个 主机 标签 需要 使 用 CE 多 余 的 主机 标签 
$ sudo docker run -e CATTLE_HOST_LABELS='foo=bar&hello=world' -d --privileged \ 
-v /var/run/docker.sock:/var/run/docker.sock rancher/agent:v0.8.2 \ 
http://<rancher -server -ip>:8080/v1/projects/1a5/scripts/<registrationToken> 


注意 : rancher/agent 的 版 本 与 Rancher 服务 端的 版 本 相关 联 。 你 需要 检查 自 定义 命令 
义 便 获 取 所 使 用 版 本 的 正确 标识 。 


自动 实现 的 主机 标签 


Rancher 自动 创建 关于 Linux 内 核 版 本 和 Docker Engine 版 本 的 主机 标签 。 


Key Value 首 述 
io.rancher.host.linux_kernel_version nn pi ~ a 
主机 的 Docker hk A 主机 上 的 Docker 
io.rancher.host.docker_version i 

(例如 : 1.10.3 ) Engine 版 本 


代理 后 的 主机 

为 了 支持 代理 后 面 的 主机 ， 你 需要 编辑 Docker daemon 来 指向 代理 。 详 细 指 导 列 在 我 们 的 添 
加 自 定 义 主 机 页 面 

访问 来 自 于 云 提 供 商 的 主机 


在 Rancher 启动 主机 后 ， 你 可 能 需要 访问 主机 。 我 们 提供 了 所 有 在 启动 设备 时 生成 的 证 书 ， 
可 通过 下 载 方式 获取 。 在 主机 的 下 拉 菜 单 中 点 击 Machine Config。 那 将 会 下 载 一 个 包含 所 有 
证 书 的 tar.gz 文件 。 


AT SSH 进入 你 的 主机 ， 进 入 你 的 终端 /命令 行 。 进 入 所 有 人 证书 存放 的 文件 夹 ， 然 后 通过 使 用 
id_rsa 人 证书 以 便 ssh 进入 主机 。 


$ ssh -i id rsa root@<IP_OF_HOST> 


克隆 主机 


由 于 启动 云 提 供 商 上 的 主机 需要 使 用 access key， 你 可 能 想 要 更 简单 的 创建 另 a 
需要 再 次 输入 所 有 的 证 书 。Rancher 提供 了 通过 克隆 这 些 证 书 来 启动 一 个 新 主机 的 功能 。 
主机 的 下 拉 菜 单 中 选择 Clone © A844 24] |] Add Host 页 面 并 带 有 克隆 主机 的 所 使 用 
+4 o 


编辑 主机 


所 有 能 对 主机 做 的 操作 选项 都 位 于 主机 的 下 拉 菜 单 中 。 在 Infrastructure -> Hosts 页 面 中 ， 
下 拉 标 识 将 会 在 你 和 鼠标 放置 在 主机 上 时 出 现 。 如 果 你 点 击 主机 名 字 来 查看 主机 的 更 多 信息 ， 
下 拉 标 识 将 会 出 现在 页 面 的 右上 角 。 它 将 会 位 于 主机 状态 的 旁边 


如 果 你 选择 Edit， 你 能 更 新 名 字 ， 描 述 或 主机 的 标签 。 


停 用 /激活 主机 


停 用 主机 将 使 主机 进入 Inactive 状态 。 在 此 状态 中 ， 将 不 会 部 署 新 的 容器 。 任 何 此 主机 上 的 
活动 的 容器 将 会 保持 激活 ， 并 且 你 仍然 能 够 对 这 些 容器 执行 操作 enge ) 。 主 机 将 
仍然 连接 到 Rancher 服务 端 。 从 主机 的 的 下 拉 菜 单 中 选择 Deactivate 。 


当主 机 处 于 Inactive 状态 ， 你 能 通过 点 击 主机 下 拉 菜 单 中 的 Activate 使 主机 重 回 Active 状 


& 


你 将 需要 执行 健康 检查 以 便 Rancher 在 其 他 不 同 的 主机 上 启动 你 服务 中 的 容器 。 


注意 : N Rancher 中 一 台 主 机 失效 (例如 处 于 reconnecting X inactive 状态 )， 


删除 主机 


为 了 从 服务 端 删除 主机 ， 你 需要 在 下 拉 菜 单 中 操作 一 系列 的 步骤 。 


选择 Deactivate 。 当 主机 完成 停 用 ， 主 机 将 显示 Inactive 状态 。 选 择 Delete。 服 务 端 将 开始 
将 主机 从 Rancher 服务 端 移 除 的 过 程 。 在 它 完 成 删除 后 首先 显示 的 状态 将 会 是 Removed > & 
从 UI 中 立即 消失 前 ， 将 会 继续 以 便 完成 移 除 过 程 ， 并 进入 Purged KA © 


如 果 使 用 Rancher 在 云 提供 商 上 创建 的 主机 ， 主 机 将 会 在 云 提供 商 处 删除 。 如 果 主 机 是 通 
使 用 自 定义 命令 添加 的 ， 主 机 将 会 保留 在 云 提供 商 处 。 


注意 : 对 于 自 定义 主机 ， 所 有 容器 ， 和 包括 Rancher 代理 端 将 会 继续 保留 在 主机 上 。 


删除 Rancher 外 的 主机 


如 果 你 的 主机 在 Rancher 外 被 删除 了 ，Rancher 服务 器 将 会 继续 展示 此 主机 直到 它 被 移 除 。 
最 终 ， 这 些 主机 将 显示 为 处 于 Reconnecting 状态 但 无 法 重新 连接 。 你 能 够 Delete 这 些 主机 
用 于 从 UI 上 移 除 他 们 。 


AI É E SL EYL 


Amazon EC2 


Azure 


Digital Ocean 


Exoscale 


Packet 


Rackspace 


其 它 驱动 


基础 架构 /证 书 


Rancher E x 


为 了 轻松 的 部 署 复杂 的 Stacks (应 用 栈 ) ，Rancher 为 我 们 设计 了 称 为 Catalog (应 用 程序 模 
WAR”) 的 功能 。 访 问 Catalog 页 , 将 会 看 到 有 两 个 子 页 : ALL 以 及 LIBRARY。ALL 是 所 有 已 
启用 的 应 用 程序 模板 集 (包括 LIBRARY 下 的 项 目 和 自 建 项 ) ， 而 Library 页 下 面包 含 了 
Rancher certified catalog 和 community-catalog。 前 者 是 Rancher Labs 公 司 官方 认证 的 项 目 ， 
后 者 是 由 社区 维护 的 项 目 。Rancher Labs 公 司 仅 仅 只 对 通过 认证 的 项 目 进 行 维护 与 支持 。 两 
者 的 不 同 点 可 以 从 项 目 缩 略 图 顶部 是 否 带 有 "Certified" 进 行 区 分 。 


Rancher 系 统 的 admin 角 色 可 以 对 目录 下 的 项 目 进 行 添加 或 删除 操作 ， 在 Admin -> Settings 
页 我 们 可 以 选择 在 系统 里 显示 (启用) 哪些 目录 项 。 添 加 一 个 目录 项 并 不 复杂 ， 只 需要 给 定 
一 个 名 字 和 一 个 URL。 对 于 URL 的 内 容 要 求 是 它 必须 能 被 git clone 处 理 。 当 添加 一 个 目录 
项 后 ， 它 会 立即 显示 在 目录 页 并 处 于 可 操作 状态 。 


URL 示 例 : httos://github.com/rancher/rancher-catalog.git (下 面 会 提 到 如 何 准备 正确 的 文件 
及 目录 结构 并 提交 至 git 服 务 器 ) 


如 果 Rancher Server 处 于 http proxy 代 理 服 务 器 之 后 ， 那 么 需要 修改 Docker 守 护 进 程 的 局 动 参 
数 ， 否 则 catalog 将 无 法 正常 运作 。 


尼 动 模板 


首先 找到 需要 的 模板 ， 可 以 进行 关键 字 搜索 或 直接 进行 类 型 过 滤 。 找 到 模板 之 后 就 可 以 点 击 
View Details 按 钮 进去 ， 卉 写 必须 的 信息 之 后 就 可 以 点 Launch 按 钮 启用 模板 了 。 


1. 对 于 模板 项 的 版 本 ， 系 统 默 认 采 用 的 是 当前 最 新 的 版 本 ， 如 果 需 要 的 话 ， 仍 然 可 以 选择 
存在 的 其 它 老 版 本 。 

2， 给 定 一 个 新 的 stack 名 字 ， 必 要 时 填写 stack 的 描述 信息 。 

3. 选择 或 填写 Configuration Options 里 的 项 目 , 这 些 项 目 因 不 同 的 目录 特性 而 不 同 ， 如果 
4] Start Services after creating > 那么 一 旦 点 击 Launch， 服 务 将 会 自动 启动 。 

4， 点 击 Launch 以 创建 基于 模板 的 应 用 栈 (stack)。 点 击 Preview 则 可 以 以 展开 方式 查 
阅 docker-compose.yml 和 rancher -compose.yml 等 文件 内 容 ， 这 些 正 是 用 以 创建 应 用 栈 
(stacks) 的 模板 文件 。 


升级 模板 


Rancher 里 有 个 很 棒 的 功能 是 当 新 版 本 的 模板 上 载 到 目录 之 后 ， 它 会 提示 你 有 新 版 本 可 用 。 当 
点 击 Upgrade Available 时 ， 当 选择 了 某 个 版 本 之 后 ， 需 要 查阅 一 下 Configuration Options 
是 否 也 需要 做 出 相应 的 改变 ， 确 认 无 误 之 后 即 可 点 击 Save 保 存 交 更 。 


当 所 有 的 服务 被 升级 之 后 ， 服 务 service 和 应 用 栈 stack 的 状态 会 显示 为 Upgraded。 如 果 对 升 
级 的 结果 表示 满意 ， 那 么 最 后 就 可 以 点 击 stack 下 拉 菜 单 里 的 Finish Upgrade 以 确认 升级 。 注 
意 : 一 旦 确认 完成 升级 过 程 ， 就 没 法 再 回 退 到 旧 的 版 本 了 。 


版 本 回 退 


如 果 在 升级 过 程 中 遇 到 错误 ， 需 要 回 退 至 升级 前 的 正常 状态 ， 可 以 在 stack 的 下 拉 菜 单 里 选择 
Rollback 回 退 至 之 前 的 版 本 。 


创建 私有 目录 


Rancher catalog 服务 定义 了 一 套 配置 文件 的 格式 ， 只 需 按 照 格式 来 添加 配置 文件 ，catalog 服 
务 就 能 通过 git 自 动 把 它 加 到 rancher-server 的 容器 的 模板 目录 下 。 


目录 结构 
目录 模板 在 Rancher 里 的 显示 内 容 基于 环境 的 集群 管理 类 型 。 


e Cattle 环境 : Ul 里 的 条 目 来 自 templates 文件 夹 
e Kubernetes 环境 : UI 里 的 条 目 来 自 kubernetes-templates 文件 夹 
e Swarm 环境 : UIE iA A KÉ swarm-templates 文件 夹 


- templates OR kubernetes-templates OR swarm-templates 
- cloudflare 

- 0 

|-- docker-compose.yml 

|-- rancher-compose.yml 

al 

|-- docker-compose.yml 

|-- rancher-compose.yml 

- catalogIcon-cloudflare.svg 


| 

| 

| 
|-- 
| 

| 

| 
|-- config.yml 

在 主 目录 里 ， 需要 有 一 个 templates 文件 夹 ， templates 文件 夹 里 包含 了 已 创建 好 的 每 个 


catalog 条 目 。 我 们 推荐 对 每 一 个 catalog 条 目 使 用 一 个 简单 的 模板 名 ， 并 和 文件 夹 名 称 保持 一 
致 。 


在 catalog 条 目 文件 内 (例如 cloudflare ) 对 应 于 创建 的 每 一 个 不 同 版 本 都 有 一 个 对 应 的 文件 
夹 。 第 一 个 版 本 对 应 的 文件 夹 名 是 0 ， 后 续 版 本 则 依次 增加 ， 例 如 第 二 个 版 本 对 应 
ka la Peale a 的 文件 夹 内 容 ， 就 提供 了 对 stack 升 级 其 模板 至 新 版 本 的 渠道 
作为 一 种 可 选 方案 ， 还 可 以 直接 对 o 文件 夹 也 就 是 第 a Tees 
部 署 这 个 条 目 


注意 : 每 个 catalog 条 目 必须 使 用 独立 单词 ， 所 以 请 在 较 长 的 完整 名 称 中 使 用 连 
代替 空格 。 而 在 config.yml 的 name 部 分 内 你 可 以 使 用 空格 。 


Rancher 目 录 里 显示 的 目录 文件 
在 catalog 条 目 文件 夹 里 有 两 个 文件 ， 其 细节 决定 了 条 目 如 何在 Rancher Catalog 内 具体 显示 。 


o 第 一 个 配置 文件 config.ym 包含 了 条 目 细节 。 


name: # Name of the Catalog Entry 
description: | 
# Description of the Catalog Entry 
version: # Version of the Catalog to be used 
category: # Category to be used for searching catalog entries 
maintainer: # The maintainer of the catalog entry 
license: + The license 
projectURL: + A URL related to the catalog entry 


。 第 二 个 文件 是 catalog 条 目的 图 标 文件 ， 其 文件 名 必须 以 catalogIcon- 作为 开头 。 


对 于 每 一 个 catalog 条 目 文件 夹 ， 至 少 需要 三 项 ， 其 中 包含 两 个 文件 和 一 个 文件 夹 ， 它 们 
是 config.yml ? catalogIcon-entry.svg 和 o 文件 夹 (第 一 个 版 本 ) 7 如 果 有 多 个 版 本 el 
包含 更 多 的 文件 及 文件 夹 。 


Rancher 目录 模板 


docker -compose.yml 和 rancher- compose.yml 在 Rancher 里 是 必需 的 文件 ， 被 rancher- 
compose 工 具 调 用 以 启动 服务 ， 它 们 位 于 版 本 号 对 应 的 文件 夹 内 (例如 6 > 1%) © 


docker-compose.yml 同时 应 该 是 一 个 能 够 被 docker-compose 工具 载 入 并 启动 的 文件 ， 其 格式 
遵循 docker-compose 规 范 。 


rancher-compose.yml 则 包含 了 附加 的 信息 用 于 自 定义 catalog 条 目 。 在 .catalog 节 ， 有 一 些 
字段 是 为 了 正确 执行 catalog 条 目 所 必需 的 项 目 。 


README.md 作为 可 选项 也 可 能 被 创建 ， 其 主要 作用 在 于 提供 详尽 的 描述 说 明 或 注意 事项 。 


rancher-compose.yml 


Rancher 目录 


.catalog 
name: # Name of the versioned template of the Catalog Entry 
version: # Version of the versioned template of the Catalog Entry 
description: # Description of the versioned template of the Catalog Entry 
uuid: # Unique identifier to be used for upgrades. Please see note. 
minimum_rancher_version: # The minimum version of Rancher that supports the template 
questions: #Used to request user input for configuration options 


注意 : wid 是 一 个 必 选 参数 用 于 升级 更 新 版 本 的 场景 。 每 个 uuid 都 必须 是 唯一 的 并 且 
随 着 版 本 变化 而 增加 。 推 荐 的 格式 是 使 用 catalog 条 目 名 称 并 添加 一 个 版 本 号 前 缓 -0 > 
如 前 所 述 对 版 本 所 做 的 说 明 ， 下 一 个 版 本 前 缓 则 是 -1 © 


rancher-compose.yml 内 的 Questions 


位 于 .catalog 里 的 questions 小 节 允 许 用 户 修改 服务 的 配置 选项 。 而 文件 answers.txt 则 对 
应 地 设置 这 些 配 置 项 的 具体 值 。 


每 一 个 配置 项 都 在 rancher-compose.yml 的 questions 小 节 内 列 出 。 


,Catalog 
questions: 
- variable: + A single word that is used to pair the question and answer. 
label: + The "question" to be answered. 
description: | + The description of the question to show the user how to answer 
the question. 
default: + (Optional) A default value that will be pre-populated into the UI 
required: + (Optional) Whether or not an answer is required. By default, it's co 
nsidered “false”. 
type: + How the questions are formatted and types of response expected 


Type 

type 小 节 用 于 服务 配置 项 的 问题 及 对 应 答案 以 何 种 方式 显示 于 UI 界面 。 
合适 的 格式 有 : 

string 

显示 一 个 文本 框 ， 用 于 存放 字符 串 型 的 在 answer.txt 里 定义 的 值 。 

int 


显示 一 个 文本 框 ， 用 于 存放 被 整形 化 的 在 answer.txt 里 定义 的 值 。UI 会 对 其 数值 在 模板 启用 
前 做 合法 性 检测 。 


boolean 


显示 一 个 单 选 按钮 ， 用 于 存放 其 在 answer txt 里 定义 的 布尔 变量 值 ， 如果 布尔 值 为 Bw ， 则 
单 选 框 被 匀 选 ， 否 则 被 置 空 。 
password 


显示 一 个 文本 框 ， 用 于 存放 其 在 answer.txt 里 定义 的 密码 字符 串 内 容 。 


service 


显示 一 个 下 拉 框 ， 其 内 容 为 环境 (environment) 里 的 所 有 服务 (services)。 


enum 


显示 一 个 下 拉 框 ， 其 内 容 为 自 定义 的 options 条 目 。 


.Catalog 
questions: 
- variable: 

label: 

description: | 

type: enum 

options: # List of options if using type of “enum 
- Option 1 
- Option 2 


multiline 


显示 一 个 多 行文 本 框 。 


ku 


„catalog 
questions: 

- variable: 
label: 
description: | 
type: multiline 
default: | 

Each line 
would be shown 
on a separate 
line. 


Kubernetes 


英文 原版 与 中 文 翻 译 版 初稿 by Jordan 


To deploy Kubernetes in Rancher, you'll first need to create a new environment that has 
specified the cluster management to be Kubernetes. 为 了 在 Rancher 上 部 署 Kubernetes， 首 
先 你 需要 创建 一 个 指定 用 Kubernetes 管 理 的 集群 环境 。 


CREATING AKUBERNETES ENVIRONMENT 创建 一 个 KUBERNETES 环 境 


In the dropdown of environments, click on the Manage Environments. To create a new 
environment, click on Add Environment, select Kubernetes as the cluster management， 
provide a Name, Description (Optional). If access control is turned on, you can add 
members and select their membership role. Anyone added to the membership list would 
have access to your environment. 在 下 拉 式 环境 中 ， 点 击 管理 环境 。 为 了 创建 一 个 新 的 环 
境 ， 点 击 "Add Environment”， 选 择 Kubernetes 做 为 集群 管理 者 ， 起 一 个 名 字 ，Description 
(可 选项 )。 如果 访问 控制 权限 是 开 着 的 ， 你 可 以 增加 成 员 ， 选 择 membership 角 色 。 在 
membership 列 表 中 的 任何 成 员 都 可 以 访问 你 的 环境 。 


After a Kubernetes environment has been created, you can navigate to the environment by 
either selecting the name of the environment in the environment's dropdown in the upper 
right hand corner or by selecting Switch to this Environment in the specific environment's 
drop down. 在 Kubernetes 环 境 创建 后 ， 你 既 可 以 通过 选择 环境 名 字 又 可 以 通过 切换 环境 在 下 
拉 菜 单 中 ， 浏 览 你 的 环境 。 


NOTE: As Rancher adds support for multiple cluster management frameworks, Rancher 
currently does not support the ability to switch between environments that already have 
services running in it. 注意 : Rancher 支 持 多 种 集群 管理 框架 ， 目 前 不 支持 已 经 运行 服务 的 环 
境 之 间 切 换 。 


STARTING KUBERNETES 启动 KUBERNETES After a Kubernetes environment has been 
created, you can start the Kubernetes cluster by adding at least one host to your 
environment. The process of adding hosts is the same steps for all cluster management 
types. Once the first host has been added, Rancher will automatically start the deployment 
of the required Kubernetes components (i.e. master, kubelet, etcd, proxy, etc.). You can see 
the progress of the deployment by accessing the Kubernetes tab. 在 Kubernetes 环 境 创建 

后 ， 你 可 以 启动 Kubernetes 集 群 通过 至 少 增加 一 个 主机 到 你 的 环境 。 在 所 以 集群 管理 类 型 中 


添加 主机 的 流程 是 一 样 的 步骤 。 一 旦 第 一 个 主机 被 添加 后 ，Rancher 将 自动 开始 部 署 
Kubernetes 组 件 (如 ，master, kubelet, etcd, proxy 等 ) 。 你 可 以 通过 Kubernetes 选 项 卡 看 到 
部 署 过 程 。 


USING KUBERNETES 使 用 KUBERNETES Once the setup has completed, you can begin 
to create or manage your own Kubernetes applications via the following ways: — E A E % 
成 ， 你 就 可 以 通过 下 面 方法 开始 创建 或 管理 你 自己 的 Kubernetes 应 用 。 


RANCHER UI RANCHER A Fi Rancher provides full CRUD capability of creating 
services, replication controllers (RCs), and pods. In the Kubernetes tab, click on the one of 
these items and click Add. A kubernetes template will be shown in the Ul and is editable. 
After you have made changes to the configuration file, click on Create. Rancher 对 创建 
services, replication controllers (RCs) 和 pods 提 供 了 增删 改 查 的 能 力 。 在 Kubernetes tab? 4 
击 这 些 项 目 和 点 击 添加 ， 一 个 可 编辑 的 kubernetes 模 板 将 会 被 展现 出 来 ， 然 后 你 在 配置 文件 
修 做 一 些 改 ， 点 击 创建 。 


RANCHER CATALOG RANCHER 服务 目录 Rancher supports the capability of hosting a 
catalog of Kubernetes templates. To use a template, click on the Catalog tab. Select the 
template that you want to launch and click View Details. Review and edit the stack name， 
stack description, and configuration options and click on Launch. Rancher 支 持 Kubernetes 模 
板 的 服务 目录 的 能 力 。 要 使 用 模板 ， 请 单 击 “ 服 务 目 录 ” 选 项 卡 。 选 择 你 要 启动 的 模板 ， 然 后 单 
击 “View Details”。 审 查 和 编辑 堆栈 名 称 、 堆 栈 描述 和 配置 选项 ， 然 后 单 击 “ 启 动 ” 


If you want to add your own templates to Kubernetes, you add them to the Rancher catalog 
and place your templates in a kubernetes-templates folder. 如 果 你 想 添加 自己 的 模板 到 
Kubernetes， 你 将 它们 添加 到 Rancher 的 服务 目录 ， 把 你 的 模板 放 在 Kubernetes 模 板 文件 夹 
里 。 


KUBECTL KUBECTL To configure your own kubectl to talk to your newly created 
Kubernetes cluster, go to Kubernetes -> kubectl -> Generate Config to generate the 
necessary kube/config_file that you can download and add to your local directory. 为 了 配置 
你 自己 的 kubectl 与 新 创建 的 Kubernetes 集 群 关 联 ， 通 过 Kubernetes -> kubectl -> Generate 
Config 生成 所 需 的 kube/config file， 你 可 以 下 载 并 添加 到 你 的 本 地 目录 。 


KUBECTL VIASHELL KUBECTL VIASHELL Rancher provides a convenient shell access to 
amanaged kubectl instance that can be used to manage Kubernetes clusters and 
applications. Rancher 提 供 了 一 个 方便 的 Shell 进 入 到 托管 kubectl 实 例 来 管理 Kubernetes 集 群 
和 应 用 。 


KUBERNETES NAMESPACES KUBERNETES 命 名 空间 Rancher supports the ability to 
manage different Kubernetes namespaces. In the upper right hand corner, you will be able 
to see which Namespace that you are working in. After the first host is added, Rancher 


creates the default namespace. Rancher 提 供 了 支持 管理 不 同 的 Kubernetes 命 名 空间 的 能 
力 。 在 右上 角 ， 你 可 以 看 到 你 在 工作 中 的 那个 名 字 空 间 ， 在 添加 第 一 主机 后 ，Rancher 创 建 默 
认 的 命名 空间 。 


ADDING NAMESPACES 添加 NAMESPACES To add an additional namespace into 
Kubernetes, click on the current namespace and a dropdown of available namespaces and 
Manage Namespaces will appear. Click on Manage Namespaces. 为 了 添加 一 个 额外 的 命名 
空间 到 Kubernetes， 点 击 当前 命名 空间 和 下 拉 可 用 的 命名 空间 > “Manage Namespaces‘ & 
出 现 。 单 击 "Manage Namespaces“ ° 


In the Namespaces page, click on Add Namespace. Update the configuration file and click 
Create. 在 命名 空间 中 的 页 面 中 点 击 “Add Namespace”， 更 新 配置 文件 ， 然 后 单 击 “ 创 建 ”。 


EDITING NAMESPACES 编辑 NAMESPACES For existing namespaces, in the Namespaces 
page, click on Edit in the namespace’s dropdown to update it. Click on Save. 对 于 现 有 的 命 
名 空间 ， 在 命名 空间 的 页 面 中 点 击 编辑 命名 空间 的 下 拉 菜 单 ， 然 后 更 新 ， 点 击 保存 。 


SWITCHING NAMESPACES 切换 NAMESPACES In the dropdown of namespaces, you can 
select the namespace that you want to launch services in to switch between the 
namespaces. 在 命名 空间 的 下 拉 菜 单 ， 你 可 以 选择 你 想 启 动 服务 的 命名 空间 ， 在 名 称 空间 之 
间 进 行 切换 。 


Swarm 


若 想 在 Rancher 中 使 用 Swarm， 首 先 需 要 创建 一 个 集群 管理 方式 配置 为 Swarm 的 环境 。 


创建 Swarm 集群 管理 的 环境 


在 右上 角 的 环境 下 拉 菜 单 中 ， 单 击 管理 环境 。 要 创建 一 个 新 环境 ， 单 击 新 建 环境 ， 选 择 
Swarm 作为 集群 管理 方式 ， 提 供 名 称 ， 说 明 (TH) 。 如 果 打 开 了 访问 控制 功能 ， 你 可 以 添 
加 成 员 并 赋予 相应 的 角色 。 所 有 位 于 成 员 列 表 的 用 户 都 可 以 访问 此 新 增 环境 。 


创建 完 由 Swarm 管 理 的 环境 后 ， 你 可 以 通过 在 右上 角 的 环境 下 拉 框 中 根据 环境 名 字 切 换 到 对 
应 的 环境 。 


注意 Rancher 目 前 支持 多 种 集群 管理 方式 ， 但 是 不 支持 在 已 有 服务 运行 的 环境 中 切换 集 


群 管理 方式 。 


尼 用 Swarm 


创建 完 由 Swarm 集群 管理 的 环境 后 ， 现 在 可 以 添加 至 少 一 台 主 机 来 启用 Swarm 集群 。 对 于 不 
同 的 集群 管理 方式 ， 添 加 主机 的 过 程 都 是 一 样 的 。 一 旦 添加 完 一 台 主 机 ，Rancher 就 会 自动 部 
署 Swarm 需 要 的 组 件 (比如 swarm 和 swarm-agent) 在 主机 上 。 你 可 以 在 Swarm 标签 页 看 到 
部 署 的 进度 。 


注意 Swarm 不 需要 安装 在 所 有 的 主机 上 。 
使 用 Swarm 


swarm 组 件 部 署 完 成 后 ， 你 就 可 以 通过 以 下 方式 来 创建 或 者 管理 Swarm 程序 : 


RANCHER 


用 户 可 以 在 Rancher 有 界面 上 完成 创建 、 获 取 、 更 新 、 销 毁 项 目的 所 有 操作 。 在 Swarm 标签 页 ， 
选择 项 目 并 单 击 创建 项 目 。 创 建 项 目 时 ， 你 可 以 在 界面 上 通过 上 传 文件 或 者 粘贴 文件 内 容 的 
方式 来 提供 docker-compose.yml。 如 果 你 的 项 目 装配 模板 中 包含 环境 变量 ， 你 需要 通过 添加 
变量 替换 的 方式 来 声明 变量 ， 最 后 单 击 创建 。 


RANCHERA x 


Rancher 支 持 加 载 整套 Swarm 模板 。 如 果 使 用 模板 ， 可 以 单 击 目 录 标 签 页 。 选 择 你 想 加 载 的 模 
板 并 单 击 查看 详情 。 审 核 并 编辑 工作 站 名 称 ， 工 作 站 说 明和 相关 的 配置 ， 然 后 单 击 加 载 。 如 
果 你 想 添 加 模板 到 Swarm， 你 可 以 先 添加 到 Rancher 目 录 中 ， 并 放置 在 swarm-templates 目 


为 了 配置 你 的 工作 机 器 用 来 管理 Swarm， 你 可 以 依次 单 击 Swarm->CLI-> 生 成 配置 来 生成 必要 
的 API 秘 钥 并 将 配置 文件 放置 在 docker-cli.zip 压 缩 文 件 中 。 遵 循 界面 上 的 说 明 去 配置 TLS 并 连 
4% #1] Docker ° 


SHELL 脚 本 


Rancher 提 供 了 一 套 方 便 的 SHELL 接 口 来 执行 docker 或 者 docker-compose 命 令 。 


使 用 标签 


升级 Rancher 


如 果 你 运行 Rancher 服 务 端 时 没有 使 用 外 部 数据 库 , Rancher 服 务 端 数据 库 在 你 的 Rancher 服 
务 端 容 器 内 . 我 们 将 要 使 用 运行 中 的 Rancher 服 务 端 容器 来 创建 一 个 数据 容器 . 数据 容器 将 会 通 
过 使 用 --volumes-from 以 用 来 局 启动 新 的 Rancher 服 务 端 . 或 者 ， 你 MAA EE 器 中 拷贝 出 

来 到 主机 的 某 个 目录 然后 绑 定 挂 载 数据 库 . 


注意 : 如 果 你 使 用 了 外 部 数据 库 , 你 能 停止 原始 的 Rancher 服 务 端 容器 然后 使 用 相同 的 外 
部 数据 库 指引 来 局 bal ana hee 1. 端 启动 运行 后 ,你 就 能 删除 老 的 


Rancher 服 务 端 容器 了 . 注意 : 如 果 你 仅 停止 容器 ,如 果 你 的 机 器 重启 ,容器 将 会 由 于 有 -- 
restart=always 而 重新 运行 . 


通过 创建 数据 容器 升级 Rancher 


2 


a 
s 


A 


停止 容 


一 
< 
9 


we 


$ docker stop <container_name_of_original_server> 


2. 创建 一 个 rancher-data 容器 . 注意 : 此 步骤 可 以 跳 过 ,如 果 你 过 去 已 经 升级 过 并 且 已 经 有 


= 


了 一 个 rancher-data 容器 . 


$ docker create --volumes-from <container_name_of_original_server> \ 
--name rancher-data rancher/server:<tag_of_previous_rancher_server> 


3， 拉 取 最 近 的 Rancher 服 务 端 镜像 . 注意 : 如 果 你 跳 过 此 步骤 然后 尝试 运行 最 近 的 镜像 , 将 不 
会 自动 拉 取 更 新 后 的 镜像 . 


$ docker pull rancher/server:latest 


4. 户 动 一 个 新 的 Rancher 服 务 端 并 使 用 来 自 rancher-data 容器 的 数据 库 . Rancher 内 的 a 
何 修 改 都 将 会 保存 到 rancher-data 容器 .如 果 你 在 服务 端 件 到 了 关于 日 志 锁 的 异常 ,请 
考 如 何 处 理 日 志 锁 


注意 : 取决 于 你 运行 了 Rancher 服 务 端 A, 某 些 数据 库 迁 移 可 能 花费 比 预计 更 长 的 
时 间 . 请 不 要 在 升级 中 间 时 停止 升级 ,否则 在 下 次 升级 时 将 会 遇 上 数据 库 迁 移 错误 


$ docker run -d --volumes-from rancher-data --restart=always \ 
-p 8080:8080 rancher/server:latest 


如 果 你 在 原始 的 Rancher 服 务 端 安装 时 设置 过 任何 环境 参数 或 传 入 过 |dap 认 证 ， 
你 将 ERE: 命令 中 加 入 这 pare eee 


5. .. 端 . 注意 : 如 果 你 a --restart 而 在 你 
的 机 器 重启 后 重新 运行 . 我 们 建议 在 你 的 升级 成 功 后 移 除 此 容器 . 


通过 局 动 时 使 用 绑 定 挂 载 升 级 Rancher 


停止 运行 中 的 Rancher 服 务 端 容器 


一 人 
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$ docker stop <container_name_of_original_server> 


2， 从 服务 端 容器 中 拷贝 数据 库 文件 出 来 . 注意 :如 果 你 已 经 有 数据 库存 储 在 主机 上 了 ,你 能 够 
跳 过 此 步骤 .另外 , 如 果 数 据 库 已 经 被 拷贝 到 了 容器 外 面 , 它 将 会 在 //mysql/ 里 面 ,因为 
Docker 的 拷贝 方法 如 此 . 在 绑 定 挂 载 到 容器 里 时 一 定 要 考虑 到 这 一 点 . 如 果 你 开始 绑 定 挂 
载 ,你 将 不 需要 输入 mysqli. 


$ docker cp <container_name_of_original_server>:/var/lib/mysql <path on host> 


3， 现 在 为 文件 夹 设置 UID/GID 以 便 容 器 内 的 mysqdl 用 户 对 mysql 挂 载 有 正确 的 所 有 权 . 


$ sudo chown -R 102:105 <path on host> 


4 开局 新 的 服务 端 容 器 . 


$ docker run -d -v <path_on_host>:/var/lib/mysql -p 8080:8080 \ 
--restart=always rancher/server: latest 


主意 : 如 果 你 是 从 前 一 个 容器 中 拷贝 出 来 的 数据 库 , 确 保 在 主机 路 径 最 后 是 1 将 很 重 
Al 否则 目录 会 在 错误 的 地 方 结 来 . 


Rancher 代 理 端 


每 个 Rancher 代 理 端 版 本 都 国定 了 相应 的 Rancher 服 务 端 版 本 .如 果 你 升级 了 Rancher 服 务 端 并 
且 Rancher 代 理 端 需要 升级 , 它 将 会 自动 升级 代理 端 到 最 新 版 本 的 Rancher 代 理 端 


对 于 使 用 rancher/agent-instance 镜像 的 任何 东 西 ,运行 中 的 容器 将 获得 升级 ,甚至 是 容器 器 的 镜 
ero 最 近 版 本 .对 于 Network Agent, 这 将 在 有 关 网 ere 器 触发 时 进行 (例如 , 添加 
a 器 ,删除 一 个 容器 ). 对 于 Load Balancers, 升 级 将 在 下 一 次 负载 均衡 配置 更 新 时 进行 ( 例 
如 , 目 ie 实例 重 局, 新 的 目标 服务 加 入 ,主机 名 路 由 规则 变更 ,负载 均衡 实例 重启 等 ). 


没有 互联 网 接 入 的 用 户 


没有 互联 网 的 用 户 需要 将 最 新 的 rancher/agent-instance 下 载 到 他 们 自 己 的 镜像 库 . 为 了 升级 
网 络 代 理 的 版 本 ,你 需要 通过 UI 手工 停止 网 络 代 理 端 并 移 除 他 们 . 在 缺失 网 络 代 理 端的 主机 上 ， 
任何 触发 网 络 的 事件 都 将 会 引起 一 个 新 的 网 络 代理 端 (最 新 版 本 ) 启 动 . 为 了 升级 你 的 负载 均衡 
的 版 本 , 你 将 需要 重新 创建 它们 以 便 获 取 到 最 新 版 本 的 rancher/agent-instance . 


A Rancher 做 贡献 


参与 开发 


查看 GitHub 代码 库 , 在 我 们 的 wiki 文档 里 有 给 Rancher 开发 人 员 写 的 如 何 上 手 开发 工作 的 文 
档 。 


AM cowpoke 来 开始 您 的 代码 协作 开发 之 旅 吧 | 


代码 库 


在 我 们 的 GitHub 首页 您 能 看 到 Rancher 所 有 的 相关 代码 库 ， 但 是 下 面 我 们 会 简要 介绍 
Rancher 所 使 用 的 几 个 核心 的 代码 库 。 


Rancher Repo: 这 个 代码 库 的 功能 是 把 所 有 其 它 相关 代 码 库 集成 在 一 起 。 
Cattle Repo: 这 是 用 来 开发 Rancher 核心 功能 的 代码 库 。 
Ul Repo: 这 是 用 来 开发 Rancher 图 形 用 户 界面 部 分 的 代码 库 。 


Community Catalog Repo: 这 里 是 Rancher Catalog 所 使 用 的 所 有 社区 贡献 的 模板 。 我 们 欢 
迎 您 在 这 里 贡献 模板 。 


Rancher-Compose Repo: 这 是 rancher-compose CLI 功能 的 代码 库 。 它 总 是 会 与 
docker/libcompose 保持 同步 。 


KT Bug 


如 果 您 发 下 了 任何 Bug 或 者 有 任何 使 用 问题 ， 请 通过 填写 Issue 的 方式 联系 我 们 。 尽 管 我 们 
的 Rancher 中 有 很 多 代码 库 ， 我 们 还 是 想 让 大 多 数 的 bug 都 能 被 记录 在 Rancher repo > È 
样 就 不 会 被 错过 | 


如 果 您 想 帮助 优化 我 们 的 文档 ， 请 提交 PR 到 我 们 文档 的 代码 库 docs repo ， 或 者 点 击 文档 页 
面 上 的 Edit this page 按钮 ， 它 会 直接 带 您 进入 页 面 修订 功能 。 


API È R 


API 有 可 以 从 web 浏 览 器 访问 的 用 户 接口 。 这 是 查看 资源 ， 执 行动 作 ， 以 及 查看 等 价 于 cURL 
命令 执行 的 HTTP 请 求 & 回 应 。 点 击 API 来 获得 URL endpoint 来 访问 API > 


ThisEnvironment 


API & Keys 


Registries 





点 击 端点 链接 : 


API Keys Add API Key 





Endpoint for "Default" Environment: 
http://rancherserverip :8080/v1/projects/1a5 


IKE 


API 中 一 些 资源 类 型 命名 和 当前 UI 上 所 用 的 术语 ， 并 不 一 致 。 尤 其 是 : 


UI API Description 
Environment project 一 组 物理 资源 ， 例 如 主机 
一 个 环境 是 一 和 Ry E = 
Stack environment | z a 不 境 是 一 组 服务 以 及 rancher-compose 所 操作 


在 这 文档 中 ， 我 们 使 用 UI 所 用 的 术语 进行 描述 ， 在 不 同 点 也 会 提供 额外 的 声明 。 这 些 混乱 将 
会 在 未 来 的 /v2 版 本 API 清 除 。 


验证 


te R Access Control 启 动 的 话 ，API 请 求 必 须 包 含 验证 信息 。 验 证 操作 通过 带 有 API keys 的 
HTTP 基 本 验证 来 完成 。API| 密 钥 或 者 属于 一 个 (U1) Environment/ (API) Project， 只 能 访问 该 
Environment ; 或 者 属于 一 个 Account， 能 够 访问 该 账户 所 有 的 Environment， 也 能 够 创建 新 的 
Api 密 钥 。 在 UI 上 有 单独 的 JSON Web Token 接 口 。 


一 个 环境 的 API 窒 铀 


环境 的 API 密 钥 能 够 在 UI 中 创建 ， 查 看 [API 8 Kes[(/configuration/api-keys/)。 密 钥 所 属于 一 
个 环境 ， 而 且 完 全 有 权 管 理 该 环境 ， 但 无 权 管 理 其 他 环境 。Membership roles 并 不 支持 密 
钥 。 


MEP 7 APIS 4A 
账户 的 AP| 密 钥 当 前 并 没有 在 Ul 中 显示 。 你 可 以 点 击 浏览 器 的 API 页 面 来 创建 一 个 


e 点 击 UI 上 的 Endpoint 链 接 

e 导航 到 /v1/apikeys 

e 点 击 Create 

e 选择 你 要 创建 蜜 钥 的 accountId 

e 可 选择 设置 name 和 description 

e 点 击 Show Request ?’ 然后 Send Request 
e 保存 回应 中 的 publicValue 和 secretValue 


Account #A £8 ci 建新 的 Environments， 也 能 够 用 来 通过 /v1/projects 来 访问 多 个 
Environments。 这 些 密 钥 所 采用 的 Membership roles 限 制 该 Account 哪 些 Environments 以 及 哪 
些 动作 能 够 使 用 。 


作用 域 


e 大 部 分 的 资源 被 一 个 Environment 所 拥有 ， 并 通 
过 /v1/projects/<project_id>/<resources> 地 址 进行 访问 。 

© 因为 环境 证 书 只 能 够 存 取 一 个 Environment(project)， 你 可 以 选择 跳 
过 /project/<project_id> 部 分 。 -例如 ， 如 果 你 在 project 1a5 使 用 了 一 个 Environment 
API 密 钥 ， 那 么 /v1/projects/1as FAT v1 > /v1/projects/1a5/hosts 等 同 
于 /vi/hosts ° 

e。 这 篇 文档 一 般 只 涉及 更 短 的 /v1/<type> 版 本 .如 果 使 用 了 Account 密 钥 ， 则 将 适当 的 
environment 添 加 到 路 径 中 。 


这 些 API 一 般 都 是 RESTful API， 但 拥有 一 些 特 性 使 得 客户 端 能 够 查看 任何 资源 的 定义 ， 因 而 


可 以 


编写 通用 的 客户 端 ， 而 不 是 每 种 资源 类 型 编写 特定 代码 的 客户 端 。 对 那些 想 费 力 深入 通 


用 API 规 范 细节 的 人 ， 查 看 过 里 


每 种 类 型 有 一 个 Schema， 负 责 描 述 : 


o 到 达 该 资源 类 型 的 collection 的 URL 

o 该 资源 拥有 的 所 有 域 ， 连 同 域 的 类 型 ， 域 的 基本 验证 规则 ， 它 们 是 必须 还 是 可 选 等 . 

o 该 类 型 资源 能 够 执行 每 个 动作 ， 以 及 输入 和 输出 (和 schemas 一 样 ) 

o 每 个 域 允许 的 过 滤 方 式 

o collection 中 哪些 HTTP 动 词 方法 对 其 或 者 其 中 独立 的 资源 可 用 
因此 理论 上 你 能 够 只 需要 加 载 schemas 列 表 就 知道 API 的 一 切 。 这 就 是 实际 上 Ul 如 何 工作 
的 ， 它 并 没有 包含 和 Rancher 特 定 的 代码 。 获 取 Schemas 的 URL， 作 为 一 个 x-Api- 
schemas 头 部 ， 在 每 一 个 HTTP 回 应 被 发 送 。 从 该 URL， 你 可 以 通过 访问 每 一 个 schema 
的 collection 链接 ， 来 知道 哪里 显示 资源 ; 通过 返回 资 资源 的 其 他 links 来 获取 其 他 信 
Bo 


IS 


实际 上 ， 你 可 能 只 想 构 建 URL 字 符 串 。 我 们 强烈 建议 限制 构建 的 URL 字 符 串 只 在 顶级 显 
示 collection( /v1/<type> ) 或 者 获取 一 个 特定 的 资源 ( /v1/<type>/<id> ) 时 使 用 。 任 何 更 底 
层 的 动作 都 将 在 将 来 版 本 改变 。( 译 者 注 : 这 里 指 用 户 应 尽 通过 可 能 返回 的 HTTP 回 应 信 
息 中 提取 想 要 资源 的 URL， 不 要 根据 当前 版 本 资源 的 URL 结 构 自 己 构建 。) 

资源 间 的 关系 称 为 links。 每 个 资源 都 包含 一 个 Links 表 ， 其 中 包含 link 的 名 字 以 及 获取 
link 信 息 的 URL. 再 次 强调 ， 你 应 该 通过 发 送 GET 请 LASER 源 以 及 使 用 links RPA 
URL ; 而 不 是 自己 构建 这 些 字 符 串 。 

大 多 数 资 源 都 有 些 动作 ， 用 来 处 理 某 事 或 者 改变 资源 的 状态 . 通过 发 送 post 请 求 

到 action 表 中 的 URL 来 执行 你 想 要 的 动作 . 一 些 动作 会 需要 输入 或 者 会 产生 输出 ， 请 查 
看 每 种 类 型 资源 或 者 schemas 的 独立 文档 来 获取 特定 信息 . 

编辑 资源 ， 则 发 送 一 个 带 有 资源 的 域 数据 的 put HTTP 请 求 到 你 想 要 改变 的 资源 

的 links.self 链接 .未 知 域 或 者 不 可 编辑 的 域 将 被 忽略 . 

删除 资源 ， 则 发 送 一 个 DELETE HTTP 请求 到 资源 的 links.self 链接 . 注意 一 些 资源 必须 
要 在 删除 之 前 停止 ;被 删除 的 资源 仍然 通过 API 根 据 指 定 资源 ID 来 恢复 . 


创建 资源 ， 发 送 一 个 post HTTP 请 求 schema 中 的 collection URL( 也 即 是 /v1/<type> ). 


大 多 数 的 collections 能 够 在 服务 端 通过 HTTP 的 检查 参数 按照 通 A E. filter RE 
哪些 域 能 够 被 过 滤 ， 以 及 哪些 值 是 你 的 请 求 过 滤 的 . API UI 控 制 了 安装 过 滤 的 过 程 ， 为 你 显示 
正确 的 请 求 。"equals" 和 field=value 相 匹 配 。 修 饰 符 可 以 添加 到 域名 ， 人 

de > field gt=42 意思 就 是 field 大 于 42 。 更 多 细节 查看 API spec 。 


HE 


大 多 数 的 collections 在 服务 端 通过 HTTP 的 查询 参数 按照 通用 域 进 行 排序 . sortLinks 表 将 显示 
哪些 排序 是 可 用 的 ， 连 同 显示 已 经 按照 该 方式 排序 的 collection 的 URL. 如 果 指 定 的 话 ， 它 也 将 
包含 当前 回应 是 以 何 种 方式 排序 的 信息 。 


分 页 


API 回 应 默认 以 每 页 100 资 源 的 限制 进行 分 页 .可 以 通过 添加 limit=1669 查询 参数 来 将 上 限 提 
升 到 1000. collection 回 应 中 的 pagination 会 告诉 你 是 否 收 到 全 部 结果 ; 如 果 没 有 收 到 全 部 结 
果 ， 将 会 有 一 个 链接 指向 下 一 页 。 


WebSockets 


一 些 Rancher 特 性 ， 比 如 容器 日 志 ，shell 访 问 ， 统 计 都 使 用 websockets 来 传输 信息 流 。 通 过 
API 来 使 用 : 


o 点 击 适当 的 链接 或 者 执行 适当 的 动作 

e 回应 将 包含 一 个 URL( 以 ws:// 或 者 wss:// 开头 ) 以 及 一 段 长 的 token FH FP. 

e 打开 一 个 指向 返回 URL 的 WebSocket 客 户 端 

e token 是 由 Rancher server 签 名 的 ， 允 许 所 在 的 主机 容器 授权 这 次 请 求 ， 所 以 它 作 为 一 个 
HTTP 的 头 部 ， 如 authorization: Bearer <token_string> ， 发 送 给 Rancher server ° 

。 如 果 你 通过 web 浏览 器 发 送 请 求 ， 你 不 能 发 送 包 容 任意 HTTP 头 部 的 请 求 ， 因 此 你 可 以 选 
择 的 是 将 token 添 加 到 URL 中 作为 URL 查 询 参 数 来 代替 ， 如 token=<token_string> ° 


Common Resource Fields 


在 API 中 ,最 常见 和 只 读 的 资源 域 并 不 在 资源 视图 中 显示 。 为 了 让 用 户 更 容易 浏览 资源 域 列表 ， 
些 资源 


我 们 将 这 些 


域 
accountld 
created[TS] 
id 
kind 


removeTime 


removed 


transitioning 
transitioningMessage 


transitioningProgress 


uuid 


源 域 从 列表 中 移 除 。 


= 


account 
date 
string 


string 


date 


bool 


enum 
string 
int 


string 


注释 
相关 联 账号 的 唯一 识别 符 。 
资源 创建 的 起 始 日 期 /时 间 。 
资源 的 唯一 识别 符 。 
资源 更 具体 的 类 型 划分 。 


资源 被 移 除 的 时 间 , 如 果 资 源 没 有 被 移 除 , 则 该 值 将 
A null ° 


如 果 资 源 已 经 被 移 除 , 则 为 路 。 已 移 除 的 资源 不 会 回 
到 collection 列 表 , 但 能 单独 通过 ID 来 检索 。 


资源 转换 的 状态 : yes , no ,或 者 error 2 
转换 过 程 中 出 现 的 信息 ， 或 者 产生 的 错误 。 
转换 期 间 的 进度 估算 ， 范 围 是 0-100。 


资源 的 通用 唯一 识别 码 。 这 在 Rancher 安 装 过 程 中 始 
终 保 持 唯一 。 


账号 


Rancher 上 所 有 资源 要 么 被 一 个 账户 (account) 拥 有 ， 要 么 由 该 账户 创建 。 


api% 4A 
如 果 启 动 了 访问 控制 ，API 密 钥 (apiKey) 将 会 提供 访问 Rancher API 的 能 力 。 由 每 个 环 


境 (environment) 创 建 访问 密 钥 (accesskey) 以 及 秘密 密 钥 (secretkey) 对 能 够 直接 用 来 调 
用 API 或 者 和 rancher-compose 一 起 使 用 。 


DE + 
1£ # (certificate) FT ZSSLA 4102] A 2 941 Z (loadbalancer) ° 
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容器 (container) 用 来 表示 主机 上 的 一 个 Docker 容 器 。 


dns 服 务 


API 中 的 "dns 服务 "(dnsService) 在 用 户 界面 和 Rancher 文 档 中 被 称 为 服务 别名 。 我 们 在 
API 文 档 中 使 用 用 户 界面 术语 来 称呼 。 一 个 服务 别名 有 人 允许 为 你 可 被 发 现 的 服务 添加 
DNS 记录 的 能 力 。 


环境 


API 中 的 "环境 "(environment) 在 用 户 界 面 和 Rancher 文 档 中 被 称 为 栈 (stack)。 我 们 在 
API 文 档 中 使 用 用 户 界面 术语 来 称呼 。Rancher 栈 (stack) 和 dockercompose 工 程 反映 
了 同样 的 概念 。Rancher 栈 (stack) 代 表 一 组 构建 典型 应 用 和 负载 程序 的 服务 。 


外 部 服务 


外 部 服务 (externalService) 允 许 添加 任意 IP 或 者 主机 作为 服务 的 能 力 能 够 以 服务 的 方式 
被 发 现 。 


主机 


主机 (host) 在 Rancher 中 是 资源 的 最 小 单元 ， 满 足以 下 最 低 要 求 的 任何 虚拟 或 物理 
Linux 服 务 器 都 能 表示 自己 是 一 台 Rancher 主 机 。 


任意 支持 Docker 1.10.3 的 Linux 发 型 版 本 。 

必须 能 够 经 由 http 或 者 https 的 方式 通过 预先 配置 的 端口 (默认 为 8080) 访 问 Rancher 
Server ° 

* 必须 对 属于 同一 个 环境 中 的 主机 可 路 由 ， 来 为 Docker 容 器 使 用 Rancher 的 跨 主机 网 
络 功能 。 


身份 证 明 
当 Rancher 启 动 了 访问 控制 ， 身 份 证 明 (identity) 是 一 个 对 象 (例如 
ldap_group , github_user ) 在 Rancher 的 表示 。 身份 证 明 中 的 externalld 是 在 认证 系 
统 中 用 来 表示 对 象 的 唯一 识别 符 。 除 非 身份 证 明 的 角色 被 作为 项 目 成 员 
(projectMember) El > ER] € 8 Anull 。 


负载 均衡 服务 


Rancher 使 用 HAProxy 实 现 了 一 个 可 管理 的 负载 均衡 器 (loadbalancer)， 能 够 手动 地 将 
规模 扩大 到 其 他 主机 上 。 通 过 将 负载 均衡 器 添加 或 者 "连接 "到 基本 服务 ， 服 务 均衡 器 
就 能 用 来 为 单独 的 容器 分 化 网 络 和 应 用 流量 。 被 "连接 "的 基本 服务 中 所 有 基本 的 容器 
将 自动 被 Rancher 注 册 为 服务 均衡 器 (loadbalancer) 目 标 。 


机 器 


无 论 何 时 Rancher 使 用 docker-machine 在 Rancher 中 创建 主机 ， 就 会 创建 机 器 
(machine) 条 目 。 在 用 户 界 面 上 添加 任意 类 型 的 主机 。 


挂 载 
挂 载 (mount) 是 指 在 数据 卷 和 容器 中 目录 位 置 的 关系 。 


项 目 


用 户 界 面 和 Rancher 文 档 把 API 中 的 "项 目 (project)" 称 为 环境 (environment)。 在 API 文 档 
中 ,我 们 使 用 用 户 界面 上 的 术语 来 描述 。 所 有 主机 和 任何 Rancher 资 源 ( 比 如 ， 容 器 , 负 
载 均衡 器 等 ) 在 被 创建 后 都 属于 一 个 环境 .环境 的 拥有 者 决定 谁 能 查看 和 管理 这 些 资 

源 。Rancher 当 前 支持 每 个 用 户 能 管理 和 佬 请 其 他 用 户 到 他 所 属 的 环境 ， 也 允许 为 不 
同 的 工作 量 创建 多 个 环境 。 例 如 ， 你 可 能 想 创 建 一 个 "开发 "和 一 个 分 离 的 "产品 "环境 ， 
这 些 环境 各 自 带 有 自己 的 一 系列 资源 ， 以 及 应 用 程序 部 署 限制 的 用 户 访问 。 


项 目 成 员 


用 户 界 面 和 Rancher 文 档 把 API| 中 的 "项 目 成 员 (projectMember)" 称 为 环境 成 员 
(environmentMember)。 环 境 成 员 是 环境 中 所 有 成 员 的 列表 。 环 境 成 员 是 一 个 身份 证 
AA (identity) ° 


镜像 仓库 


镜像 仓库 (registry) 是 镜像 存储 处 的 地 点 。 镜 像 仓 库 可 以 是 DockerHub，Quay.io， 或 者 
是 定制 的 私有 镜像 仓库 。 


镜像 仓库 证 书 


镜像 仓库 证 书 (registryCredential) 用 来 授权 镜像 仓库 (registry)。 


这 是 结构 定义 (schema) 资 源 


服务 
Rancher 对 服务 (service) 采 用 了 标准 Docker Compose 术 语 ， 同 时 定义 一 个 基本 服务 为 
同一 个 Docker 镜 像 创 建 的 一 个 或 多 个 容器 。 在 同样 的 栈 中 一 旦 一 个 服务 (消费 者 ) 被 链 
接 到 另 一 个 服务 (生产 者 )， 会 自动 创建 一 条 映射 到 每 一 个 容器 实例 的 DNS 记 录 ， 这 条 
记录 能 够 "正在 消费 "的 服务 发 现 。 在 Rancher 中 创建 服务 的 其 他 好 处 包括 ":" 


服务 高 可 用 -拥有 Rancher 自 动 监控 容器 状态 和 维护 服务 想 要 的 规模 的 能 力 。 
健康 监控 -拥有 为 容器 健康 设置 基本 监控 阅 值 的 能 力 。 


存储 池 
存储 池 (storagePool) 是 参与 到 共享 存储 的 主机 名 单 。 


数据 卷 
数据 卷 (volume) 能 够 关联 到 容器 或 者 存储 池 。 


一 个 容器 能 够 有 多 个 数据 卷 ， 容 器 能 被 映射 到 数据 卷 所 在 的 容器 上 的 挂 载 连 接 。 
存储 池 拥 有 多 个 存储 卷 。 数 据 卷 只 对 那些 部 署 到 作为 存储 池 一 部 分 的 主机 上 的 容器 是 
有 效 的 。 当 创 建 一 个 数据 卷 ， 你 不 能 直接 将 它 关 联 到 存储 池 。 你 只 需要 在 指定 一 个 驱 
动 ， 在 分 配 过 程 中 ，Rancher 将 会 将 其 解析 给 一 个 存储 池 。 


Rancher OS 


快速 安装 指南 


如 果 你 有 特别 的 RancherOS 主 机 要 求 ， 请 浏览 运行 RancherOS 指 南 ， 本 指南 的 主要 讲述 使 
用 docker machine 来 启动 RancherOS 和 介绍 RancherOS 能 够 做 什么 


If you have a specific RanchersOS machine requirements, please check out our guides on 
running RancherOS. With the rest of this guide, we'll start up a RancherOS using docker 
machine and show you some of what RancherOS can do. 


4% M Docker Machine È #RancherOS 


Launching RancherOS using Docker Machine 


前 进 之 前 ， 你 需要 安装 Docker Machine4=VirtualBox ° 一 旦 你 安装 VirtualBox 和 Docker 
Machine， 它 只 需要 一 个 命令 就 可 以 运行 RancherOS ° 


Before moving forward, you'll need to have Docker Machine and VirtualBox installed. Once 
you have VirtualBox and Docker Machine installed, it's just one command to get RancherOS 
running. 


$ docker-machine create -d virtualbox --virtualbox-boot2docker-url https://releases.ra 
ncher.com/os/latest/rancheros.iso < 实例 机 器 名 > 


就 是 这 么 简单 ! 你 已 经 启动 和 运行 了 一 个 RancherOS 实 例 。 That's it! You're up and running 
a RancherOS instance. 


要 登录 到 该 实例 ， 只 需 使 用 docker-machine A ° To log into the instance, just use the 
docker-machine command. 


$ docker-machine ssh < 实例 机 器 名 > 


771% RancherOS 


A First Look At RancherOS 


在 RancherOS 中 运行 两 个 Docker 守 护 进 程 。 首 先是 所 谓 的 system-docker， 这 就 是 
RancherOS 运 行 的 系统 服务 ， 如 NTPD 和 系统 日 志 。 您 可 以 使 用 system-docker 命令 来 控 
制 system-docker 守 护 进程 。 


另 一 个 守护 进程 是 docker， 它 可 以 通过 使 用 正常 的 docker 命令 来 访问 。 


There are two Docker daemons running in RancherOS. The first is called system-docker, 
which is where RancherOS runs system services like ntpd and syslog. You can use the 
system-docker Command to control the system-docker daemon. 


The other Docker daemon running on the system is docker, which can be accessed by 
using the normal docker command. 


当 你 第 一 次 启动 RancherOS， 还 没有 容器 运行 在 'docker 守护 进程 。 不 过 ， 如 果 你 对 运行 system- 
docker 的 命令 ， 你 会 看 到 一 些 RancherOS 系 统 自 己 维护 的 服务 。 


When you first launch RancherOS, there are no containers running in the docker daemon. 
However, if you run the same command against the system-docker instance, you'll see a 
number of system services that are shipped with RancherOS. 


ZE : system-docker 只 能 由 root 用 户 使 用 ， 所 以 每 当 你 需要 使 用 system-docker I > XZ 
使 用 sudo 命令 。 


Note: system-docker can only be used by root, so it is necessary to use the sudo 
command whenever you want to interact with system-docker . 


$ sudo system-docker ps 


CONTAINER ID IMAGE COMMAND CREATED 
STATUS PORTS NAMES 

4710a91a0729 rancher/os-docker:v0.4.4 US SD Ene Sn 6 minutes ago 
Up 6 minutes docker 

7ef4fad1612c rancher/os-console:v0.4.4 > /usr/sbinkenteryashr 7 6 minutes ago 
Up 6 minutes console 

1b436b6b7fdb rancher/os-network:v0.4.4 "/usr/sbin/entry.sh /" 6 minutes ago 
Up 6 minutes network 

2ce47a55d1bd rancher/os-ntp:v0.4.4 /uspAsbinlentry Sule a: 6 minutes ago 
Up 6 minutes ntp 

c2237144ec41 rancher/os-udev:v0.4.4 "/usr/sbin/entry.sh /" 6 minutes ago 
Up 6 minutes udev 

5373e592dc51 rancher/os-acpid:v0.4.4 /usr/sbinkenteryashr 7 6 minutes ago 
Up 6 minutes acpid 

c5d8cd81a94c rancher/os-syslog:v0.4.4 Ausr/Asbanlentry sh 6 minutes ago 
Up 6 minutes syslog 

一 些 容器 在 启动 时 运行 ， 和 其 余 时 间 ， 如 console > docker 等 。 这 些 容器 始终 运行 。 


Some containers are run at boot time, and others, such as the console , docker , etc. 
containers are always running. 


FF 2612 HA RancherOS 


Using RancherOS 


部 署 一 个 Docker 容 器 


Deploying a Docker Container 


让 我 们 尝试 使 用 docker 守护 进程 部 署 一 个 正常 的 Docker 容 器 。 该 RancherO S docker 守护 等 
同 于 其 他 任何 Docker 环 境 ， 使 一 切 正 常 Docker 命 令 的 工作 。 Let's try to deploy a normal 
Docker container on the docker daemon. The RancherOS docker daemon is identical to 
any other Docker environment, so all normal Docker commands work. 


$ docker run -d nginx 


你 可 以 看 到 ，nginx 镜 像 的 容器 启动 并 运行 。You can see that the nginx container is up and 


running: 
$ docker ps 
CONTAINER ID IMAGE COMMAND CREATED S 
TATUS PORTS NAMES 
e99c2c4b8b30 nginx "nginx -g "daemon off" 12 seconds ago U 
p 11 seconds 80/tcp, 443/tcp drunk_ptolemy 


部 署 一 个 系统 服务 容器 


Deploying A System Service Container 


下 面 是 一 个 简单 的 Docker 容 器 安装 Linux-dash ， 它 是 用 于 监控 Linux 服 务 器 最 小 的 低 开销 网 
络 信息 中 心 。 该 Dockerfile 将 是 这 样 的 : The following is a simple Docker container to set up 
Linux-dash, which is a minimal low-overhead web dashboard for monitoring Linux servers. 
The Dockerfile will be like this: 


FROM hwestphal/nodebox 
MAINTAINER hussein.galal.ahmed.11@gmail.com 


RUN opkg-install unzip 

RUN curl -k -L -o master.zip https://github.com/afaqurk/linux-dash/archive/master.zip 
RUN unzip master.zip 

WORKDIR linux-dash-master 

RUN npm install 


ENTRYPOINT ["node", "server" 


使 用 hwestphal/ nodebox 镜像 EAN T busybox 44) 46 4% ? 并 安装 node.js 和 npm ° 我 们 下 
载 的 Linux-dash 的 源 代码 ， 然 后 运行 服务 器 。 Linux-dash 将 默认 在 端口 80 上 运行 。Using 
the hwestphal/nodebox image, which uses a busybox image and installs node.js and npm. 
We downloaded the source code of Linux-dash, and then ran the server. Linux-dash will run 
on port 80 by default. 


要 使 用 systemd-docker 运行 这 个 容器 使 用 下 面 的 命令 : 


To run this container with system-docker use the following command: 


$ sudo system-docker run -d --net=host --name busydash husseingalal/busydash 


在 这 文 行 命 令 中 ， --net= host 告诉 system-docker 不 使 用 容器 化 LE 器 的 网 络 ， 并 使 用 
=. 络 代 替 。 在 运行 容器 后 您 可 以 通过 访问 http://<IP_OF_MACHINE> 看 到 监控 服务 器 。 


In the commad, we used --net=host to tell system-docker not to containerize the 
container's networking, and use the host's networking instead. After running the container, 
you can see the monitoring server by accessing http: //<IP_OF_MACHINE . 


为 了 容器 能 在 系统 重启 时 存活 ， 你 可 以 创建 `/opt/rancher/bin/start.sh 脚本 ， 并 添加 Docker 
启动 项 以 保证 每 次 启动 时 自动 启动 。To make the container survive during the reboots, you 
can create the /opt/rancher/bin/start.sh script, and add the docker start line to launch the 
docker at each startup. 


$ sudo mkdir -p /opt/rancher/bin 
$ echo “sudo system-docker start busydash” | sudo tee -a /opt/rancher/bin/start.sh 
$ sudo chmod 755 /opt/rancher/bin/start.sh 


使 用 ROS 工 具 包 


Using ROS 


可 与 RancherOS 使 用 的 另 一 种 有 用 的 命令 是 ros , 它 可 用 于 控制 和 配置 系统 。 Another useful 
command that can be used with RancherOS is ros which can be used to control and 
configure the system. 


$ ros -v 
ros version 0.0.1 


RancherOS 状 态 由 云 配 置 文件 控制 。 ros 用 于 编辑 系统 的 配置 ， 参 见 例 如 系统 的 DNS 配置 : 
RancheroOS state is controlled by a cloud config file. ros is used to edit the configuration of 
the system, to see for example the dns configuration of the system: 


$ sudo ros config get rancher.dns 
- 8.8.8.8 
- 8.8.4.4 


当 使 用 本 地 控制 台 的 Busybox， 控 制 台 的 任何 更 改 将 重启 后 会 丢失 ， 只 有 改变 

为 /home 或 /opt 将 是 持久 的 。 控 制 台 始 终 在 每 次 启动 时 执行 /opt/rancher/bin/start.sh。 你 
可 以 用 ros 局 用 持久 控制 台 和 替换 本 地 Busybox 的 控制 台 。 为 了 使 启用 Ubuntu 的 控制 台 ， 使 
用 以 下 命令 


When using the native Busybox console, any changes to the console will be lost after 
reboots, only changes to /home Or /opt will be persistent. The console always executes 
/opt/rancher/bin/start.sh at each startup. You can use ros to enable a persistent console 
and replace the native Busybox console. In order to enable the Ubuntu console, use the 
following command: 


$ sudo ros service enable ubuntu-console 


Ubuntu 的 控制 € 


$ sudo reboot 
结论 


Conclusion 


RancherOS 是 一 个 简单 的 Linux 发 行 版 非常 适合 运行 Docker。 通 过 采用 容器 化 的 系统 服务 和 利 


用 Docker 进 行 管理 ，RancherOS 希 望 能 够 为 运行 容器 提供 了 非常 可 靠 ， 易 于 管理 的 操作 系 
Bi o 


RancheroOS is a simple Linux distribution ideal for running Docker. By embracing 
containerization of system services and leveraging Docker for management, RancherOS 
hopes to provide a very reliable, and easy to manage OS for running containers. 
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裸 金 属 机 和 虚拟 机 


IPXE 


PXE 


配置 


Configuring RancherOS The configuration of RancherOS is derived from two sources. 


1. RancherOS ships with a default configuration. The default configuration cannot be 
changed, but it can be extended or overridden by cloud-config file. 

2. Cloud-config extends and overrides RancherOS default config. Cloud-config is obtained 
on boot from several sources by the cloud-init program running as a system container 
inside RancherOS. Additionally the cloud-config is read from disk if you wish to make 


local changes. 


As a convenience we provide the ros config command which makes it easy to modify the 
Cloud-config on disk. 


You can view the entire RancherOS configuration in its entirety by typing sudo ros config 


export --full. 
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自 定 义 内 核 
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ROS 工具 


A useful command that can be used with RancherOS is ros which can be used to control 
and configure the system. ros requires you to be the root user, so with the rancher user, you 
will need to use sudo. 


SUB COMMANDS 


| Command | Description | |_| 

| |config, c | 
Configure Settings | |dev, d | dev spec |env, e | Run a command with RancherOS 
environment | |service, s | Command Line interface for services and compose. | Jos | 
Operating System Upgrade/Downgrade | |tls | Setup TLS configuration | |install | Install 
RancherOS to Disk | |help, h | Shows a list of commands or help for one command | 


RANCHEROS VERSION 


If you want to check what version you are on, just use the -v option. 
$ sudo ros -v ros version v0.4.0 


HELP 


To list available commands, run any ros command with -h or --help. This would work with 
any subcommand within ros. 


$ sudo ros -h 
NAME: 
ros - Control and configure RancheroS 


USAGE: 
ros [global options] command [command options] [arguments...] 


VERSION: 
v0.4.0 


AUTHOR(S): 
Rancher Labs, Inc. 


COMMANDS: 
config, c configure settings 
dev, d dev spec 
env, e env command 


service, s Coomand line interface for services and compose. 


os operating system upgrade/downgrade 

tls setup tls configuration 

install install RancherOS to disk 

help, h Shows a list of commands or help for one command 


GLOBAL OPTIONS: 
--help, -h show help 
- -generate-bash-completion 
--version, -V print the version 
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